Skip to content
ACMS ACMS Docs

GitHub Gist Adapter

The GitHub Gist adapter stores your content schema in a GitHub Gist. It’s a simple way to make your content available remotely without setting up a full repository.

Installation

Section titled “Installation”
Terminal window
npm install @useacms/cli

Configuration

Section titled “Configuration”
import { defineConfig } from '@useacms/client';
import { localFile, githubGist } from '@useacms/cli/adapters';


export default defineConfig({
  dev: localFile({ path: './acms.json' }),
  production: githubGist({
    token: process.env.GITHUB_TOKEN,
    gistId: process.env.GITHUB_GIST_ID,
  }),
});

Options

Section titled “Options”
OptionTypeRequiredDescription
tokenstringYesGitHub personal access token with gist scope
gistIdstringYesThe ID of the Gist to use for storage

Setup

Section titled “Setup”

1. Create a GitHub Personal Access Token

Section titled “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 gist scope.
  4. Copy the token.

2. Create a Gist

Section titled “2. Create a Gist”
  1. Go to gist.github.com.
  2. Create a new Gist with a file named acms.json.
  3. Add an empty JSON object {} as the content.
  4. Save the Gist and copy its ID from the URL (e.g., https://gist.github.com/yourname/abc123def456 — the ID is abc123def456).

3. Configure Environment Variables

Section titled “3. Configure Environment Variables”
.env
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_GIST_ID=abc123def456

Usage

Section titled “Usage”

Push Content to Gist

Section titled “Push Content to Gist”
Terminal window
acms push

This uploads your local acms.json to the Gist.

Pull Content from Gist

Section titled “Pull Content from Gist”
Terminal window
acms pull

This downloads the Gist content and writes it to your local acms.json.

Sync

Section titled “Sync”
Terminal window
acms sync

Bi-directional merge between local and Gist content.

How It Works

Section titled “How It Works”

The adapter uses the Octokit library to interact with the GitHub Gist API:

  • Read: Fetches the Gist and parses the acms.json file content.
  • Write: Updates the Gist with the new content using the Gist API.

Gists support versioning, so you can view the history of changes in the Gist’s revision history.

Use Cases

Section titled “Use Cases”
  • Small to medium sites — Gists are great for storing a single JSON file.
  • Simple remote storage — No need to set up a full repository.
  • Quick collaboration — Share the Gist ID with team members.

Limitations

Section titled “Limitations”
  • Gist files are limited to 10 MB (more than enough for most content schemas).
  • No built-in access control beyond the Gist’s public/secret setting.
  • Not ideal for very large schemas with many fields.

Next Steps

Section titled “Next Steps”