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.
- Navigate to your GitHub Repository Settings > Secrets and variables > Actions.
- Create a New repository secret.
- Name:
OPENAI_API_KEY. - 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.