Run documentation maintenance in GitHub Actions

This is the GitHub Actions path. Maintain reads the push event, updates matching MDX pages, and opens a pull request. For a parent agent that should open the PR itself, use the parent-agent flow.

GitHub Actions provides the Git range, repository identity, OIDC authentication, and GitHub token. No stored Holocron key is needed.

On a GitHub Actions run, Maintain creates the branch first. OpenCode updates the selected MDX pages. When pages changed, it commits them and runs holocron maintain-open-pr with the pull request title and body. Maintain then validates the pages, pushes the branch, and opens the pull request itself. If pages changed but OpenCode skipped that command, the job fails. Local and parent-agent runs never create a branch or pull request.

  push to main
        │
        v
  holocron maintain  ──> creates holocron/maintain-<timestamp>
        │
        v
  OpenCode updates MDX pages
        │
        ├── no MDX changes ──> stop
        └── MDX files changed
                │
                v
         OpenCode commits, runs maintain-open-pr
                │
                v
         Maintain pushes, opens the PR into main

Keep GITHUB_TOKEN on the Maintain step. Maintain removes it from the OpenCode environment and uses it only after the run, to push the new branch and open the pull request. Set persist-credentials: false on actions/checkout, so the git config holds no credentials the model could push with.

Ask AI about this page

After every main-branch push

Run holocron maintain with no args. GitHub writes the push payload to GITHUB_EVENT_PATH. Maintain reads before (the branch tip before this push) and after (the new tip, this checkout), then runs git diff before..after.

That range is the whole push. Five commits in one push all count. It is not HEAD~1.

  git push (one or more commits)
           │
           v
  GITHUB_EVENT_PATH
    before  = old tip of the branch
    after   = new tip
           │
           v
  git diff before..after
           │
           v
  pages whose @/ sources sit in that diff

Checkout needs fetch-depth: 0 so those SHAs exist locally. A new-branch push has before all zeros. Maintain then uses git diff-tree --root on after.

If MDX files change, the commit lands on holocron/maintain-<timestamp> and Maintain opens one pull request into the checked-out branch, main here. See which branch the pull request targets. Nothing is committed on main or on any other existing branch. Each commit is authored by holocron.so <bot@holocron.so> (set in code through git author env vars, not by editing your repo's git config), and the PR body ends with the line PR opened by holocron.so.

1234567891011121314151617181920212223name: Maintain documentation

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - run: npx -y "@holocron.so/cli" maintain
        env:
          GITHUB_TOKEN: ${{ github.token }}

contents: write lets Maintain push the maintain branch. pull-requests: write lets it open the pull request. id-token: write authenticates Holocron over OIDC.

Protect main with a ruleset that requires a pull request and does not let GitHub Actions bypass it. The token can still create holocron/maintain-* branches.

GitHub blocks pull requests from Actions until you enable Allow GitHub Actions to create and approve pull requests in Settings, Actions, General, Workflow permissions. See the GitHub docs.

Scheduled maintenance

Use a schedule for routine audits that do not depend on a specific source change.

123456789101112131415161718192021222324252627name: Weekly documentation review

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - run: |
          npx -y "@holocron.so/cli" maintain \
            --all \
            --prompt-file .holocron/prompts/weekly-review.md
        env:
          GITHUB_TOKEN: ${{ github.token }}

Which branch the pull request targets

The pull request targets the branch that is checked out. There is no option for it. To target another branch, check it out.

Checkout	Pull request base
a branch (push, `workflow_dispatch`)	that branch, also a feature or preview one
`actions/checkout` with `ref: docs`	`docs`
detached HEAD on a `release` event	`target_commitish`, if it is a branch name
any other detached HEAD (tag, SHA)	the repository default

12345      - uses: actions/checkout@v4
        with:
          ref: docs
          fetch-depth: 0
          persist-credentials: false

Maintain branches off the checked-out commit, so that commit must already be on origin/<base>. Otherwise the pull request would carry unrelated commits, and Maintain fails before it starts OpenCode. The release target branch is only a guess, and this check catches a wrong guess.

Maintain does not run on pull_request events. Their checkout is a merge commit that is on no branch. It also refuses to run when the checked-out branch is a holocron/maintain-* branch, so a workflow that runs on every branch never opens a pull request into its own maintain branch.

The maintain branch is not rebased. It starts at the commit that triggered the run, and GitHub merges it like any other pull request. It only conflicts when someone else edits the same pages first.

Do not cancel active runs

Do not set cancel-in-progress: true for push maintenance. A later push compares only its own before and after states, so cancelling the preceding run can leave its source changes unreviewed.

A run that changes no MDX files creates no branch and no pull request.

Use your own model

The workflows above use the Holocron-hosted model and bill the project's Pro subscription. OIDC is enough. No provider API key.

To run Anthropic, OpenAI, or any other OpenCode provider, pass --model provider/model and set that provider's env var. Holocron auth is not used. See the OpenCode providers page for the supported keys.

Use a dedicated provider key. The OpenCode session can run any shell command and can read the environment, including the provider key. Maintain removes GITHUB_TOKEN, GH_TOKEN, HOLOCRON_KEY, and the GitHub OIDC request token from that environment, and it rejects the run if files outside the selected pages change.

1234- run: npx -y "@holocron.so/cli" maintain --model anthropic/claude-sonnet-4-5
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    GITHUB_TOKEN: ${{ github.token }}

You can drop id-token: write when the Holocron-hosted model is not used. Keep contents: write and pull-requests: write so Maintain can still open the pull request.