GitHub Actions Automation

GitHub Actions Automation

Keep your AI context files perfectly in sync with your documentation by automating the generation process. By integrating ContextMD into your CI/CD pipeline, you ensure that LLMs and Agents always have access to the latest technical specifications, API signatures, and logic.

Prerequisites

To run ContextMD in a headless environment, you must provide an OpenAI API key.

1. Navigate to your GitHub Repository Settings > Secrets and variables > Actions.
2. Create a New repository secret.
3. Name: OPENAI_API_KEY.
4. Value: Your OpenAI API key.

Basic Workflow: Regenerate on Push

The following workflow runs whenever changes are pushed to the main branch. It uses npx to run the CLI without requiring a pre-installed dependency and commits the updated context.md back to your repository.

name: Update AI Context

on:
  push:
    branches: [ main ]
  workflow_dispatch: # Allows manual triggering

jobs:
  generate-context:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Generate Context File
        run: npx contextmd-cli https://docs.yourproject.com -o context.md
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

      - name: Commit Updated Context
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update AI context file [skip ci]"
          file_pattern: 'context.md'

Scheduled Updates

If you are tracking external documentation that you do not control, use a schedule trigger to keep your context fresh (e.g., every Monday at midnight).

on:
  schedule:
    - cron: '0 0 * * 1'

Configuration Options for CI

When running in automation, you may want to tune the output using CLI flags:

| Flag | Purpose | Recommended for CI | | :--- | :--- | :--- | | --limit <number> | Caps the number of pages crawled to control OpenAI token costs. | --limit 50 | | --output <path> | Defines where the file is saved (e.g., ai/context.md). | --output docs/ai-context.md | | --key <key> | Pass the API key directly (though OPENAI_API_KEY env var is preferred). | N/A |

Advanced: Uploading as Artifacts

If you prefer not to commit the generated file back to your source code, you can upload it as a workflow artifact for use in other jobs or manual download.

      - name: Upload Context Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ai-context
          path: context.md

Handling Large Sites

For documentation sites with hundreds of pages, the CI job may take several minutes due to AI processing. Ensure your GitHub Action timeout is sufficient (default is 360m, which is plenty) and consider using the --limit flag to focus on the most critical sections of your documentation.