Skip to main content
The ChatFeatured Git-based CMS integration publishes articles straight into your site’s GitHub repository. If your content lives as markdown files in Git — CloudCannon, Hugo, Jekyll, Astro, Eleventy, and most static site generators — ChatFeatured publishes by committing a markdown file (with front matter) to your repo. Your CMS syncs the commit and your site rebuilds automatically. Status: Available | Setup time: 10 minutes | Complexity: Beginner

​
How it works

Unlike API-based CMS platforms, a Git-based CMS has no content API — the repository is the CMS. When you click Publish in ChatFeatured, we:
  1. Convert your article to markdown with YAML front matter matching your site’s schema
  2. Commit it to your repository (e.g. content/posts/your-article-slug.md)
  3. Your CMS detects the commit, syncs, and your site rebuilds
To your CMS and build pipeline, the commit is indistinguishable from a post written by hand — your existing workflow, build actions, and hosting are untouched.
Because articles land as normal files in your repository, your team can still open and edit them in your CMS’s editor afterward. Those edits are preserved — republishing from ChatFeatured always reads the file’s latest state before updating it.

​
Prerequisites

  • A site whose content lives as markdown in a GitHub repository
  • Permission to create a fine-grained personal access token for that repository (or someone on your team who can)

​
Setup Instructions

​
Step 1: Create a Fine-Grained GitHub Token

  1. On GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Click “Generate new token”
  3. Under Repository access, choose “Only select repositories” and pick the repository your site builds from
  4. Under Permissions → Repository permissions, set Contents to Read and write. If you plan to publish via pull request, also set Pull requests to Read and write
  5. Generate the token and copy it (it starts with github_pat_)
Scope the token to one repository with only the permissions above. ChatFeatured never needs access to any other repository or permission — a tightly scoped token limits exposure if it’s ever leaked.

​
Step 2: Find Your Branch and Content Path

  1. Branch: the branch your CMS syncs and builds from (often main)
  2. Content path: the repository folder where your blog posts live — for example content/posts on Hugo sites, or content for many Astro and Next.js sites
  3. Open an existing post file in your repository to confirm the folder and see your front matter format. Note the file extension too — if your posts are .mdx files, set File format to .mdx in the integration settings so published posts match (some content pipelines only pick up one extension)

​
Step 3: Connect in ChatFeatured

  1. In ChatFeatured, go to Integrations → Git-based CMS
  2. Enter your GitHub Repository as owner/repo-name
  3. Enter the Branch and Content Path from Step 2
  4. Paste your GitHub Access Token from Step 1
  5. Optionally enter your Site URL (e.g. https://www.example.com) so ChatFeatured can link to published posts
  6. Optionally enter a URL Pattern (e.g. /blog/{slug}/) describing how your site turns a post into its live URL. Leave it blank to derive the URL from the content path, which matches Hugo’s default
  7. Click “Connect repository” — the connection is tested against your repository before saving
The connection test verifies the token is valid, the repository and branch exist, and the token has write access.

​
Step 4 (Optional): Commit Featured Images to Your Repo

By default, published posts reference featured images by their ChatFeatured CDN URL. If your site expects local images:
  1. Turn on “Commit featured images” in the integration settings
  2. Enter your Image Folder — the repository folder where images belong (e.g. static/blog/uploads for Hugo)
Each publish then downloads the article’s featured image, commits it as <folder>/<slug>.<ext>, and references it site-relative in front matter. A leading static/ (Hugo) or public/ (Astro, Next.js, Eleventy) is dropped automatically, so static/blog/uploads produces /blog/uploads/your-slug.jpg.
If an image download ever fails, the article still publishes — front matter falls back to the CDN URL instead of blocking the publish.

​
Step 5 (Optional): Publish via Pull Request

By default, publishing commits straight to your configured branch. If that branch is protected, or you want to review posts before they go live, turn on “Publish via pull request” in the integration settings. Each publish then:
  1. Commits the post to a ChatFeatured-owned chatfeatured/* branch (named after the post’s file path)
  2. Opens a pull request against your configured branch
  3. Goes live when someone on your team merges the pull request (close it instead to discard the post)
Re-publishing an article while its pull request is still open adds commits to the same pull request. Once it’s merged or closed, the next publish starts a fresh one. Unpublishing works the same way — it opens a pull request that removes the file (or simply closes the still-open publish pull request if the post never reached your branch).
Pull-request publishing requires the token to have Pull requests: Read and write in addition to Contents — the connection test checks this when you save.

​
Publishing Articles

​
Publish an Article

  1. In ChatFeatured, click Publish on your article
  2. ChatFeatured commits the markdown file to your repository with a commit message like Publish "Your Title" via ChatFeatured
  3. Your CMS syncs the commit and your site rebuilds — the post is typically live within a minute or two, depending on your build time

​
Update an Article

Republishing an article commits an update to the same file — even if the article’s slug changed in ChatFeatured, the original file path is reused so your live URL never breaks.

​
Unpublish an Article

Unpublishing in ChatFeatured commits a deletion of the markdown file, and the post comes down from your site on the next build.

​
Schedule an Article

Scheduled articles are committed at the scheduled time, not when you schedule them — nothing appears in your repository until the publish moment arrives. Cancelling or rescheduling in ChatFeatured works as expected. If a scheduled publish fails (for example, the token was revoked), the article returns to review status and the scheduler is notified by email.

​
Front Matter

By default, published posts include this front matter:
  • description comes from the article’s meta description (or excerpt)
  • keywords are the article’s target keywords from ChatFeatured
  • date is preserved on republish, so editing an article never changes its visible publish date
Every site names its front matter keys differently (categories vs tags, summary vs description, custom keys like _schema). ChatFeatured supports per-site key mapping and static keys so the generated files match your existing posts exactly — contact support with an example post file from your repository and we’ll configure it for your site.

​
Troubleshooting

Cause: The token is invalid, expired, or was revokedSolution:
  • Generate a new fine-grained token (Step 1) and update it in the integration settings
  • Fine-grained tokens have an expiration date — check whether yours lapsed
  • Confirm the token was copied completely (it starts with github_pat_)
Cause: Wrong owner/name, or the token isn’t scoped to this repositorySolution:
  • Check the repository is entered as owner/repo-name with correct spelling
  • Fine-grained tokens only see the repositories selected when they were created — regenerate the token with the right repository selected
Cause: The branch name doesn’t exist in the repositorySolution:
  • Check which branch your CMS builds from in its site settings
  • Branch names are case-sensitive
Cause: The token’s Contents permission is read-onlySolution:
  • Edit the token on GitHub and set Contents to Read and write, or generate a new one
Cause: Your CMS’s sync or site build failed, or the post is being filtered by your site generatorSolution:
  • Check the commit exists in your repository (the publish status in ChatFeatured links the file path)
  • Check your CMS’s build status and logs for errors
  • Hugo hides future-dated posts by default — verify the post’s date isn’t in the future
  • If your site uses a draft front matter key, confirm your ChatFeatured front matter mapping sets it correctly
Cause: The URL pattern doesn’t match how your site actually routes postsSolution:
  • Set URL Pattern in the integration settings to match your live site, including {slug} where the post slug goes — e.g. /blog/{slug}/
  • Leave it blank only if your site follows Hugo’s default of mirroring the content path

​
Security Notes

Your GitHub token can write files to your site’s repository. Treat it like a password:
  • Use a fine-grained token scoped to a single repository with only the Contents permission
  • Set an expiration date and rotate the token periodically
  • If the blog lives in a shared repository with application code, consider moving it to its own repository before connecting
You can update the token at any time in the integration settings without re-entering the rest of the configuration — leave the token field blank to keep the current one.

​
See Also