GitHub Adapter

The GitHub adapter stores your content schema as a file in a GitHub repository. This is ideal for teams that want collaborative content editing with full Git history and branch-based workflows.

Installation

npm install @useacms/cli

Configuration

import { defineConfig } from '@useacms/client';
import { localFile, github } from '@useacms/cli/adapters';

export default defineConfig({
  dev: localFile({ path: './acms.json' }),
  production: github({
    token: process.env.GITHUB_TOKEN,
    owner: 'myorg',
    repo: 'content',
    path: 'acms.json',
    branch: 'main',
  }),
});

Options

Option	Type	Required	Default	Description
token	string	Yes	—	GitHub personal access token with repo scope
owner	string	Yes	—	Repository owner (user or organization)
repo	string	Yes	—	Repository name
path	string	No	'acms.json'	Path to the schema file in the repository
branch	string	No	'main'	Branch to read from and write to

Setup

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens.
2. Click “Generate new token (classic)”.
3. Select the repo scope (or public_repo for public repositories).
4. Copy the token.

2. Create or Choose a Repository

You can use an existing repository or create a new one specifically for content:

# Create a new content repository
gh repo create myorg/content --private

3. Configure Environment Variables

.env

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Usage

Push Content

acms push

Commits and pushes your local acms.json to the configured repository and branch.

Pull Content

acms pull

Fetches acms.json from the repository and writes it locally.

Sync

acms sync

Bi-directional merge between local and repository content.

How It Works

The adapter uses the Octokit REST API to read and write files in the repository:

• Read: Fetches the file content via the GitHub Contents API.
• Write: Creates a commit that updates the file, using the Contents API.

Every push creates a commit in the repository, giving you full Git history of content changes.

Use Cases

• Team collaboration — Multiple editors can work on content via PRs.
• Content review — Use pull requests to review content changes.
• Audit trail — Full commit history for compliance and accountability.
• Branch workflows — Preview content changes on feature branches.

Dedicated Content Repository

For larger projects, consider a dedicated content repository separate from your code:

myorg/my-site          # Application code
myorg/my-site-content  # ACMS content (acms.json)

This separation keeps content changes out of your code repository and allows different access permissions.

Next Steps

• Learn about Vercel Edge Config for edge deployments
• Explore deployment options