Set up Code-to-Docs with GitHub

View as Markdown

Run Code-to-Docs in GitHub Actions with the event-catalog/agents action. New to Code-to-Docs? Read the introduction first.

Before you start

You need:

An EventCatalog in a GitHub repository (the catalog repository), with the catalog at the root of the repository.
A GitHub repository with code to document (the source repository).
An API key for an AI model provider.

Setup

In your source repository, add two secrets under Settings → Secrets and variables → Actions:

ANTHROPIC_API_KEY, or the key for your model provider.
EVENTCATALOG_TOKEN, a GitHub token that can read your catalog repository, push branches to it and open pull requests. Or use a GitHub App.

Then add the workflow:

.github/workflows/eventcatalog.yml
on:
  pull_request:
    types: [closed]

jobs:
  code-to-docs:
    # Only once the pull request is merged.
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: event-catalog/agents@v2
        env:
          # The key for your model's provider. This one is for the default model.
          # Using another provider? Swap this variable and set `model` below.
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          # The agent workflow to run.
          agent: code-to-docs
          # Your catalog repository, in owner/repo format.
          catalog-repo: your-org/your-catalog
          # A token that can read your catalog, push branches and open pull requests.
          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
          # Optional: the model to use. Defaults to anthropic/claude-sonnet-4-6.
          # model: openai/gpt-5.1

Replace your-org/your-catalog with your catalog repository. Keep fetch-depth: 0: the agent needs it to compare the pull request with its base branch.

To check it works, merge a pull request that changes your architecture, such as a new event or a changed schema. The agent opens a pull request in your catalog, and comments on your pull request with a link to it.

Choose when it runs

The workflow above runs Code-to-Docs when a pull request merges, which we recommend. To run it while the pull request is open instead, so reviewers see the catalog update next to the code:

on:
  pull_request:
    types: [opened, synchronize, reopened]

Remove the job's if when you do. See the introduction for how the two compare.

Use pull_request events, not push to your main branch. The agent needs the pull request to compare it with its base branch and to comment on it.

Use it across your organization

Choose who reviews. To send each catalog update to the team that owns that part of the catalog, add a CODEOWNERS file to your catalog repository:

.github/CODEOWNERS
/domains/Payments/  @acme/payments-platform
/domains/Orders/    @acme/ordering-platform

Set up many repositories at once. Keep the workflow in one place as a reusable workflow, and call it from each repository:

.github/workflows/eventcatalog.yml in each repository
on:
  pull_request:
    types: [closed]

jobs:
  eventcatalog:
    if: github.event.pull_request.merged == true
    uses: acme/.github/.github/workflows/eventcatalog-agents.yml@main
    secrets: inherit

Use organization secrets for your model provider key, and a GitHub App instead of a personal token.

Configuration

Input	Required	Default	Description
`agent`	No	`code-to-docs`	The workflow to run. This workflow is the default.
`catalog-repo`	Yes		Your catalog repository, in `owner/repo` format.
`catalog-ref`	No	`main`	The catalog branch to read, and to open pull requests against.
`catalog-token`	No	`github.token`	A token that can read the catalog repository, push branches to it and open pull requests.
`github-app-client-id`	No		Client ID of a GitHub App. Used instead of `catalog-token`.
`github-app-private-key`	No		The private key of that GitHub App. Pass it from a secret.
`model`	No	`anthropic/claude-sonnet-4-6`	The model the agent uses. See models.
`ignore-paths`	No	Build and dependency folders	Comma-separated paths or glob patterns to leave out of the review.

By default, ignore-paths leaves out folders such as node_modules, dist and build. Your list replaces the defaults, so keep the folders you still want left out:

with:
  ignore-paths: node_modules,dist,build,src/generated,**/*.test.ts

Use models in your AWS account

To use Amazon Bedrock, use an amazon-bedrock/ model and give the job AWS credentials:

permissions:
  id-token: write # for AWS OIDC
  contents: read
  issues: write
  pull-requests: write
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/eventcatalog-agents
      aws-region: eu-west-1
  - uses: event-catalog/agents@v2
    with:
      agent: code-to-docs
      catalog-repo: your-org/your-catalog
      catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
      model: amazon-bedrock/eu.anthropic.claude-sonnet-4-6

Use a GitHub App

Instead of a personal access token, you can give the agent a GitHub App. Catalog pull requests then come from the App's bot account, there's no personal token to replace when someone leaves, and each run gets a token that only works on the catalog repository and expires after an hour.

Create a GitHub App in your organization with Contents and Pull requests set to Read and write. Turn off the webhook.
Generate a private key, and install the App on your catalog repository.
In your source repository, save the App's Client ID as a variable and its private key as a secret, and pass them instead of catalog-token:

with:
  agent: code-to-docs
  catalog-repo: your-org/your-catalog
  github-app-client-id: ${{ vars.EVENTCATALOG_APP_CLIENT_ID }}
  github-app-private-key: ${{ secrets.EVENTCATALOG_APP_PRIVATE_KEY }}

Versions

Use event-catalog/agents@v2 for the latest v2 release, or an exact release such as event-catalog/agents@v2.1.0, which never changes. Releases are listed on GitHub.

Before you start​

Setup​

Choose when it runs​

Use it across your organization​

Configuration​

Use models in your AWS account​

Use a GitHub App​

Versions​