Publish Content Engine content to GitHub MDX

GitHub publishing lets Content Engine turn a saved Studio asset into an MDX file in your website's repository. You map directories in the repo to Content Engine content types (for example, everything in content/blog is a blog post). When you publish, GTM Engine writes the file into the mapped directory, then either opens a pull request or commits directly and triggers a site build.

Before you start

Create a fine-grained GitHub token scoped only to the target repository. The token needs:

• Contents: Read and write
• Pull requests: Read and write if you want review PRs

If you want GTM Engine to start a site build after direct commits, create a deploy hook in your hosting provider (Vercel, Netlify, Cloudflare Pages, and similar). Deploy hooks must be https URLs. Without a deploy hook, your site's own CI (for example, a GitHub push webhook) is responsible for rebuilding.

Skip the deploy hook if your host already builds on every push to the branch (for example, a Vercel project connected to the repository through its Git integration). With both in place, each direct commit triggers two builds of the same commit.

Connect GitHub

1. Go to Settings → Integrations.

2. Connect GitHub.

3. Enter the token, repository owner, and repository name.

   Once the token, owner, and repository are filled in, GTM Engine reads the repository so you can pick branches, folders, and taxonomy JSON files from searchable lists instead of typing paths. Folders and files are read from the staging branch (or the default branch if that doesn't exist yet). You can still type a path that isn't listed.

4. Add one or more directory mappings (see below).

5. Set a staging branch and a production branch.

6. Optionally add, per environment:

   • a public URL pattern such as https://example.com/blog/{slug}, so Content Engine can save canonical URLs
   • a deploy hook URL
   • whether direct commits are allowed

7. Choose the default publish mode (Branch + PR or Direct commit).

8. Use Test connection to verify repo access, both branches, that each mapped directory exists on the staging branch, and that taxonomy files exist for mappings that declare them.

9. Save the integration.

Who can change the connection

The GitHub connection belongs to the person who connected it. Only they can change the token, repository, branches, or directory mappings, or run Test connection. Other admins can open Configure to see the settings read-only, along with who connected GitHub, so they know who to ask for changes. Everyone with Content Engine access can still publish to the mapped directories.

If the person who connected GitHub is no longer available, an admin can Disconnect GitHub. That deletes the saved token, so whoever reconnects has to enter their own token and then owns the connection.

The token and deploy hook URLs are encrypted in GTM Engine and are never returned to the browser. When you edit the integration later, leave the token or deploy hook field blank to keep the saved value. Use Remove saved deploy hook to clear a hook.

Directory mappings

Each mapping connects one Content Engine content type to one repo directory. A content type can only be mapped once. Files are written to {directory}/{slug}.mdx.

Each mapping has a format:

Blog MDX mappings can point at taxonomy JSON files for authors, categories, and tags (for example content/blog/authors.json). When they do, the publish form offers pickers populated from those files, and every reference is validated against them. Leave all three taxonomy paths blank to skip taxonomy checks for that directory.

Assets whose content type has no mapping can't be published to GitHub; Studio and the calendar show a message pointing back to the integration settings.

Publish from Studio

1. Open an approved asset in Content Engine → Content Studio.
2. Click Publish and choose GitHub.
3. Choose Staging or Production.
4. Choose Branch + PR for review, or Direct commit if direct commits are enabled for that environment. The form starts on your default mode.
5. For Blog MDX mappings, pick the author, categories, and tags, and add a main image URL and alt text if needed. To add a new author, category, or tag, choose Create new and enter its slug and name. Only entries you create this way are added to the taxonomy files, in the same commit as the post.
6. Preview the generated MDX and fix any validation issues.
7. Publish.

GTM Engine validates the frontmatter shape, taxonomy references, absolute media URLs on allowed hosts, blocked MDX JavaScript expressions, allowed MDX components, and plain string/boolean component props before writing to GitHub. GTM Engine also compares the new post's frontmatter with a sample of the posts already in the mapped directory, reading them the same way most MDX sites do (gray-matter / YAML 1.1). If existing posts store a field as one type and the new post would store it as another (for example a date where every other post has a quoted string), the publish is blocked before anything is committed, because the site would likely skip or reject the post. Fields that every existing post sets but the new post doesn't are shown as warnings in the preview and don't block publishing.

The preview runs exactly the same checks as the publish.

If someone else changes the post or a taxonomy file while you publish, the publish stops with "The repository changed while publishing; try again." Nothing is written in that case.

Builds

• Direct commit: after the commit succeeds, GTM Engine calls the environment's deploy hook. The success screen says whether a build was triggered. A failed deploy hook never fails the publish; trigger a build manually if the hook fails.
• Branch + PR: no deploy hook is called. Your site builds when the pull request is merged.

Recommended workflow

Use Branch + PR by default:

1. Publish to Staging with a PR.
2. Review the rendered staging site and GitHub checks.
3. Merge the PR when ready.
4. Publish the same asset to Production.

Once a slug has been published, Content Engine keeps it on future publishes, even if the asset title changes. After a staging post is merged into production, the asset still owns that file, so publishing to production updates it in place. Republishing also keeps the original publishedAt date and only bumps updatedAt.

If a previous publish PR for the same post was merged or closed, the next PR publish resets the branch to the target branch and opens a fresh PR. While a PR is still open, new publishes add commits to it.

Scheduling

The Content Calendar can schedule GitHub publishes with the same fields as Studio. Scheduled publishes run after approval and follow the same build rules.