> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatfeatured.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CloudCannon Integration

> Publish articles from ChatFeatured to your CloudCannon site as Git commits

The ChatFeatured CloudCannon integration publishes articles directly to your CloudCannon site. CloudCannon is Git-based — your content lives as markdown files in a GitHub repository — so ChatFeatured publishes by committing a markdown file (with front matter) to your repo. CloudCannon syncs the commit and your site rebuilds automatically.

**Status:** Available | **Setup time:** 10 minutes | **Complexity:** Beginner

## How it works

Unlike API-based CMS platforms, CloudCannon has no content API. 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. CloudCannon detects the commit, syncs, and your site rebuilds

To CloudCannon and your build pipeline, the commit is indistinguishable from a post written by hand — your existing workflow, build actions, and hosting are untouched. This works with any static site generator CloudCannon supports: Hugo, Jekyll, Eleventy, Astro, and more.

<Info>
  Because articles land as normal files in your repository, your team can still open and edit them in the CloudCannon editor afterward. Edits made in CloudCannon are preserved — republishing from ChatFeatured always reads the file's latest state before updating it.
</Info>

***

## Prerequisites

* A CloudCannon site connected to 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 CloudCannon site builds from
4. Under **Permissions → Repository permissions**, set **Contents** to **Read and write**
5. Generate the token and copy it (it starts with `github_pat_`)

<Warning>
  Scope the token to **one repository** with **only** the Contents permission. ChatFeatured never needs access to any other repository or permission — a tightly scoped token limits exposure if it's ever leaked.
</Warning>

### Step 2: Find Your Branch and Content Path

1. **Branch:** the branch CloudCannon syncs and builds from (often `main`)
2. **Content path:** the repository folder where your blog posts live — for example `content/posts` on Hugo sites
3. Open an existing post file in your repository to confirm the folder and see your front matter format

### Step 3: Connect in ChatFeatured

1. In ChatFeatured, go to **Integrations → CloudCannon**
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. Click **"Connect CloudCannon"** — 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 CloudCannon 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`.

<Tip>
  If an image download ever fails, the article still publishes — front matter falls back to the CDN URL instead of blocking the publish.
</Tip>

***

## 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. CloudCannon 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:

```yaml theme={null}
---
title: "Your Article Title"
date: 2026-07-08T15:00:00.000Z
description: "The article's meta description"
image: "/blog/uploads/your-slug.jpg"
tags:
  - "Your Tag"
keywords:
  - "target keyword"
author: "Your Default Author"
---
```

* **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

<Accordion title="'GitHub rejected the token' Error">
  **Cause:** The token is invalid, expired, or was revoked

  **Solution:**

  * 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_`)
</Accordion>

<Accordion title="'Repository not found' Error">
  **Cause:** Wrong owner/name, or the token isn't scoped to this repository

  **Solution:**

  * 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
</Accordion>

<Accordion title="'Branch not found' Error">
  **Cause:** The branch name doesn't exist in the repository

  **Solution:**

  * Check the branch CloudCannon builds from in your CloudCannon site settings
  * Branch names are case-sensitive
</Accordion>

<Accordion title="'The token can read the repository but cannot write to it' Error">
  **Cause:** The token's Contents permission is read-only

  **Solution:**

  * Edit the token on GitHub and set **Contents** to **Read and write**, or generate a new one
</Accordion>

<Accordion title="Article committed but not appearing on the live site">
  **Cause:** The CloudCannon sync or site build failed, or the post is being filtered by your site generator

  **Solution:**

  * Check the commit exists in your repository (the publish status in ChatFeatured links the file path)
  * Check your CloudCannon site'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
</Accordion>

<Accordion title="Featured image referencing the ChatFeatured CDN instead of my repo">
  **Cause:** Image committing is off, or the image download failed at publish time

  **Solution:**

  * Turn on **"Commit featured images"** and set the Image Folder in the integration settings
  * Image downloads fail soft — republish the article to retry the image commit
</Accordion>

***

## 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

<Tip>
  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.
</Tip>

***

## See Also

* [Ghost Integration](/integrations/ghost-integration) — API-based publishing for Ghost blogs
* [Webflow Integration](/integrations/webflow) — CMS with rich field mapping
* [REST API](/integrations/rest-api) — Build custom publishing workflows