Skip to main content
AI Visibility7 min read

Publish Cituna articles to a GitHub repo (Astro, Hugo, Jekyll, Eleventy)

Have Cituna commit each finished article as Markdown with YAML frontmatter, so your static site build turns it into a page. The token, the two paths, and the test to run first.

If your site builds from Markdown files in a repository, the cleanest place for an AI-written article is the same folder your other posts live in. Cituna commits one file per article, named after its slug, with YAML frontmatter, and your host builds and deploys it like any other commit. Nothing new enters your pipeline. This is the destination for Astro, Hugo, Eleventy, Jekyll collections, and Next.js sites that read posts from a content folder. It is not the destination for a site that serves articles from a database, and the next section explains why that failure is silent. Setup is four moves: copy two paths from a post that already works, make a token that can change one repository and nothing else, connect it, and press Test write before the first article is written.

What this assumes

Your site BUILDS FROM MARKDOWN FILES in a repo. Cituna commits a .md file and your build turns it into a page. If your site serves articles from a database or a CMS instead, the commit will succeed, Cituna will report the article as published, and the page will never appear anywhere. Use the webhook destination for those stacks.

1. Copy two paths from a post that already works

Open one of your existing posts in the repository on GitHub. The folder part of its path is your base path: for content/blog/hello-world.md it is content/blog. Left blank, Cituna uses content/blog; enter a single dot for the repository root.

Then open the same post on your live site and copy its address without the last part: https://example.com/blog/hello-world gives the public article URL prefix https://example.com/blog. Note whether the address ends with a slash. Take both from a real post rather than from memory: a plausible but wrong folder is the difference between a page and a file nobody reads.

On Jekyll, the _posts folder only builds files whose names start with a date, and Cituna names each file after its slug alone, so point the base path at a collection with output turned on.

Cituna tracked prompts: each buyer question with one mark per AI engine, ticked where that engine named the brand, and how many engines named it
In Cituna: every tracked prompt, with a mark for each engine that named you. Example workspace.Try it on your site

2. Create a fine-grained token for that one repository

Signed in to GitHub, open the pre-filled token form. It names the token and sets the one permission Cituna needs. By hand, it is your profile picture, then Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

Under Resource owner, choose the account or organization that owns the repository. Under Expiration, the form starts at 30 days, and publishing stops the day the token expires, so choose a longer period or put the date in your calendar.

Under Repository access, choose Only select repositories and pick the repository. Under Permissions, check that Contents is set to Read and write and add nothing else. Click Generate token and copy it; it starts with github_pat_. Classic tokens are refused, because a classic token reaches every repository on the account.

3. Connect the repository in Cituna

Publishing connections are per brand, so choose the brand in the top bar first. Open Integrations and click Connect on the GitHub card. Enter the repository as owner/name, the branch your host builds the live site from (blank means main), and the base path and public article URL prefix from step one. Paste the token, tick "Article URLs on this site end with a slash" if yours do, and click Connect GitHub.

The prefix has to be on the brand's own domain; a subdomain such as blog.example.com is fine. Cituna writes every canonical and every link to a published article from it, so later articles link to your public page, never to GitHub.

Cituna sources: the sites AI engines cite for the tracked prompts, with citations per site, the change this period and the engines citing each one
In Cituna: the sites AI engines cite for your prompts, with each one’s citations and their change this period. Example workspace.Try it on your site

4. Press Test write

Connecting only reads: it checks the token, the repository and the branch, and writes nothing. On the connected card, press Test write. Cituna commits a small file named .cituna-test.md to your base path and deletes it again, so you know the token, the branch and the folder all accept a commit before a single article is written. Your host may run two builds.

A pass reads "Write access verified. A test file was committed and removed", and the repository's history shows Cituna write test and Remove Cituna write test. If it fails, the message says what GitHub refused.

5. Turn on the daily article

Open Articles. In the AutoSEO setup, pick the GitHub tile under "Where should the articles go?". Under "Who approves them?" a repository has two answers: I review each one first, where nothing is committed until you click Approve & commit, or Commit automatically. There is no draft option, because a repository has no draft state and your own build decides when a committed file becomes live. Then switch on "Write articles every day" under "Start writing".

Each article arrives as one commit named "Add <slug> (Cituna AutoSEO)" and shows as Committed to GitHub in Articles. Every hour Cituna opens the article's public address, up to 48 times in its first week, and the first time it loads the article counts as live, so later articles may link to it.

Troubleshooting

Cituna says committed but nothing appears on my site.

Check your host's deploys for a build after the commit. A failed build's log says why, and a frontmatter key your build requires can be added in Articles under Writing settings, Extra frontmatter (GitHub sites). If the build passed, the base path is not the folder your site reads posts from, or your site does not build from files at all, in which case use the webhook destination. On Jekyll, _posts skips files whose names do not start with a date.

What exactly does Cituna commit?

One Markdown file per article at the base path plus the slug and .md. The frontmatter carries title, seoTitle, description, date, dateModified, canonical and tags, then image, imageAlt, imageWidth and imageHeight when the article has a hero image, and author, authorUrl and disclosure when you set a byline. A key is written only when it has a value. The body has no H1 and no JSON-LD, so your layout prints the title and adds any structured data. A hero image goes first, in its own commit, to public/images/blog/ unless you set another folder in Writing settings.

What happens if I edit an article after it was committed?

Editing in Cituna and pressing Update on GitHub commits over the same file. The slug is fixed at the first commit and never re-derived from an edited title, so a retitled article updates its file instead of orphaning it and committing a second one. If someone changed or deleted the file in the repository since, nothing is overwritten: the article offers Replace it on GitHub or Keep the site's version.

My token was rejected even though I just made it.

On the token's page on GitHub, check that it has not expired, that the repository is under Selected repositories, and that Contents is Read and write. On an organization repository, the organization has to allow fine-grained tokens, and an owner may need to approve yours under the organization's Settings, Personal access tokens, Pending requests. Until then the token can read only public resources.

Every article fails with "GitHub reported a conflict while writing the file".

Once, it is a passing clash and a retry works. Every time, the branch probably accepts changes only through pull requests, which Cituna cannot open. Check the repository's rules and branch protection, then let your account bypass the rule or connect a branch your host deploys that has no such rule.

Can Cituna open a pull request instead of committing directly?

Not today; it commits to the branch you configure. To review on GitHub, connect a branch your site does not build from and open the pull request yourself. To review in Cituna, choose I review each one first and approve each article there.

Drafted with AI assistance from our own research and Search Console data, and reviewed by Rahul A before publishing. Rules and prices change; check the linked official source before you act.

Rahul Arora

Written by

Founder, Cituna

Rahul founded Cituna and leads the product. He runs Cituna on his own sites first, in the same workspace customers use.

Find your next AI visibility fix with Cituna

Cituna asks ChatGPT, Perplexity, Gemini, Claude, Grok, Google AI Overviews and Google AI Mode your buyers' questions every day, writes the fix for every answer you are missing from, and publishes new articles to your site. Run all of it from Claude or any AI agent.

  • Your buyer questions asked on 7 AI engines every day
  • Which answers name you, and which name a competitor
  • The pages each engine cites instead of you
  • A written fix for every answer you are missing from

3-day free trial · Card required, cancel anytime · Plans from $49 a month

Join 1,783 growing businesses

The Cituna overview: visibility score, its trend and the result on each AI engine