Integration · Workflow

BetterCMS and GitHub

GitHub is where a BetterCMS site build starts. Connect a repository to a BetterCMS project and you get managed builds and previews, and the BetterCMS build Action regenerates your TypeScript types and writes a content snapshot on every run. The snapshot is what lets a server component read forms and components without an extra network call.

What connects
A repository to a project
The Action writes
Types and bcms-content.json
Category
Source control

Set it up

Four steps. Step three is the one that keeps your types honest.

  1. 01 Connect the repository
  2. 02 Add the API key as a secret
  3. 03 Regenerate types on every build
  4. 04 Read the content snapshot

Rotating the key is two places: the BetterCMS dashboard and the repository Actions secret. Nothing syncs them for you.

  1. 01

    Connect the repository

    In BetterCMS Cloud, connect the GitHub repository that holds the site. Builds, previews, forms and SEO are wired from that connection.

    Running headless instead, on Vercel, Netlify or Cloudflare? Then GitHub is your host connection and the only BetterCMS piece is the API key in step two.

  2. 02

    Add the API key as a secret

    Put BETTERCMS_API_KEY in the repository Actions secrets, not in the repository. Codegen needs a content:manage scoped key to read the schema.

  3. 03

    Regenerate types on every build

    Codegen turns the current content models into TypeScript. The BetterCMS Action runs it for you; a plain CI step does the same job in one line.

    Commit the generated file. A build that regenerates but never commits is a build that lies to your editor.

    terminal
    BETTERCMS_API_KEY=bcms_xxx npx @bettercms-ai/codegen \
      --out src/bettercms.generated.ts
  4. 04

    Read the content snapshot

    The build Action writes bcms-content.json, which holds the forms and components the site can render. readForms and readComponents pull from it, so a server component gets both without another round trip.

    Pass both into the block renderer. A page authored as sections renders nothing without the components half.

What it does not do

  • Content does not live in the repository

    This is not a git backed CMS. Entries live in BetterCMS and reach the repository as a build time snapshot. An editor publishing a typo does not produce a commit you can revert.

  • No pull request preview of content

    The Action builds the site with the content that exists when it runs. Reviewing a content change happens in the BetterCMS workflow, not in a pull request diff.

  • Secrets do not sync

    A rotated BetterCMS key has to be updated in the repository secrets by hand. Nothing detects the mismatch until a build fails.

  • GitHub only

    There is no GitLab or Bitbucket connection today. Those repositories can still build the site themselves and read the Delivery API; they just do not get the managed build path.

Questions people ask

  • Yes. The BetterCMS build Action regenerates TypeScript types from your content models and writes a content snapshot, bcms-content.json, that the framework adapters read for forms and components. A plain CI step running npx @bettercms-ai/codegen does the types half if you would rather not add the Action.

  • No. Content lives in BetterCMS and reaches your repository as a build time snapshot. Schema and content are edited in the dashboard or through MCP, not in files you commit. What is committed is the generated types file, so the code compiles against the real schema.

  • For the managed build path, no. That connection is GitHub only today. For everything else, yes. A GitLab or Bitbucket pipeline can run codegen and read the Delivery API exactly like any other CI system.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.