Connecting GitHub

Overview

A GitHub-backed website is a site whose code lives in a GitHub repository. The platform reads and writes to that repository directly — scanning it for the knowledge base, and making changes through agents, Command, or the site builder.

This guide covers the full setup: creating the repository, connecting it as an admin, and deploying it live with a custom domain.

Watch It Live: Creating And Connecting A Site

Step 1: Create The Repository

1. In GitHub, click New repository.
2. Name it something clear, like domain-businessname-website.
3. Choose Private (recommended) or Public.
4. Optional: start from a template instead of a blank repo. If your agency has a reusable site template, pick Repository template and select it. This is a good move if you build the same kind of site repeatedly — turn your best build into a template once, and start every new site from it.
5. Click Create repository.

Step 2: Get A GitHub Personal Access Token (PAT)

The platform needs a token to read and write to the repository on your behalf. GitHub calls this a Personal Access Token (PAT).

1. In GitHub, go to your profile picture → Settings.
2. Scroll down to Developer settings (bottom of the left sidebar).
3. Go to Personal access tokens → Fine-grained tokens → Generate new token.
4. Give it a name (e.g. AF Connect — Agency) and set an expiration. Setting No expiration is simpler, but an expiring token is safer — you're forced to rotate it, which matters if you ever hand off a token to a contractor or VA.
5. Under Repository access, choose the specific repository (for a one-off site) or All repositories in your account (recommended for an agency, so you don't have to regenerate a token for every new site).
6. Under Permissions, set:
   • Contents → Read and write (required if you want agents to actually make changes — read-only means the platform can see the repo but never edit it)
   • Metadata → Read-only (required, GitHub adds this automatically once Contents is set)
7. Click Generate token and copy it immediately — GitHub only shows it once.

Set It Once At The Agency Level (Recommended)

Instead of pasting a token into every site you connect, set one agency-level GitHub token that every new GitHub site inherits automatically:

1. Go to Admin → Config → Agency Connections → Agency GitHub.
2. Paste your PAT and save.

From then on, connecting a new GitHub site just needs the repository URL — no token field to fill in. The per-site token field still exists for the cases where you need it: a client who already hosts their own site on their own GitHub account and wants to keep it there. In that case, you need their token, not yours.

Step 3: Connect The Site

1. Go to the client's dashboard → Websites.
2. Click Connect Account.
3. Set Type to GitHub.
4. Paste the repository URL.
5. Give the connection a clear label (the brand or client name works well).
6. If you didn't set an agency-level token, paste the PAT from Step 2 here.
7. Save.

Once connected — and once the site actually has a live URL — the platform scans it and pulls what it finds into the knowledge base automatically. This is what lets agents answer questions about the site and make informed edits from day one, instead of starting blind.

Step 4: Test Mode vs. Master (Live) Mode

Every GitHub connection has a working-branch setting, shown as a Test / Master toggle:

• Test mode — changes agents and Command make commit to a test working branch. Nothing goes live until you review and promote it yourself.
• Master mode — changes commit straight to the branch your host (Cloudflare Pages or Vercel) deploys from, so they go live automatically once committed.

For a fresh, low-stakes site, switching to Master and saving is usually the right call — it keeps things simple. For anything mission-critical, staying in Test gives you a manual checkpoint before anything reaches production. See Website Editor for the full technical model behind this — branches, previews, and pull requests.

You can also control how often the platform re-scans the site to refresh what agents know. Leave this on Auto unless you have a specific reason to manage it by hand.

Step 5: Deploy Your Site

Once your code is in GitHub, it needs a host to actually serve the site to visitors. The platform natively tracks deployments on two hosts — Cloudflare Pages and Vercel — which means once you connect either one, you get real-time build/deploy status inside the platform (so you and the client know the moment a change goes live, or if a deploy fails).

Cloudflare Pages (Manual Setup)

1. In your Cloudflare dashboard, go to Workers & Pages → Create → Pages → Connect to Git.
2. Authorize Cloudflare's access to your GitHub account if you haven't already, then pick the repository.
3. Cloudflare detects a project name, build command, and output directory automatically for most frameworks. Some AI-generated sites need a custom build command — if you're not sure what to enter, ask your connected AI assistant what the site needs.
4. Click Save and Deploy.

Once the first deploy finishes, ask your connected AI assistant to bind the site to that Cloudflare Pages project — this links the two records together so the platform can poll build status and show deploy history for this site going forward.

Vercel (Alternative)

Vercel works the same way — connect the repo through Vercel's dashboard, then ask your assistant to bind the site to the Vercel project once it's deployed.

Step 6: Connect A Domain

A fresh deploy lives on a random subdomain (like my-site-a1b2.pages.dev) until you connect a real domain. Ask your connected AI assistant to do either of the following:

• Connect a domain you already own — the client keeps their existing registrar; the platform walks through adding one CNAME record to point it at the deployment.
• Buy a new domain — purchase it directly through Cloudflare and connect it in the same step.

Rotating A Token Without Reconnecting

If a site's PAT expires, gets revoked, or just needs rotating, you don't have to delete the connection and set it up again — that used to throw away the repo binding, branch settings, and MCP state along with the old token.

Instead, on the client's Websites tab, find the site's card and click Update Credentials (it only shows once a GitHub connection already exists). Paste the new PAT and save — everything else about the connection stays exactly as it was.

What's Next

Two things aren't covered in this guide yet, and get their own dedicated walkthroughs:

• DNS, including pulling in a domain you manage at the agency level instead of the client's
• Forms, and how form submissions get routed off a GitHub-backed site

Troubleshooting