Skip to main content

​
What you will build

An automation that updates your documentation when code is pushed to your main branch. The workflow can be built on multiple platforms, including GitHub Actions and n8n. It watches your code repository and then calls the agent API to update your documentation in a separate documentation repository. This workflow connects two separate repositories:
  • Code repository: Where you store application code. You’ll set up the automation trigger on this repository. Examples include a backend API, frontend app, SDK, or CLI tool.
  • Documentation repository: Where you store your documentation and connect to your Mintlify project. The agent creates pull requests with documentation updates in this repository.
This tutorial assumes your documentation is in a separate repository from your application code. If you have a monorepo, modify the workflow to target the directory where you store your documentation.

​
Workflow overview

  1. Someone pushes code to your main branch.
  2. The workflow triggers.
  3. The workflow calls the agent API to update your documentation.
  4. The agent creates a pull request with documentation updates in your documentation repository.

​
Choose your platform

  • GitHub Actions
  • n8n
GitHub Actions is the simplest option if your code is already on GitHub. No additional services required.

​
Prerequisites

​
Get your admin API key

  1. Navigate to the API keys page in your dashboard.
  2. Select Create Admin API Key.
  3. Copy the key and save it securely.

​
Build the workflow

​
Create the workflow file

  1. In your code repository, create a new file: .github/workflows/update-docs.yml
  2. Add this workflow: 
    name: Update Docs

on:
push:
    branches:
    - main

jobs:
update-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/github-script@v8
        env:
        MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
        PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
        with:
        script: |
            const { owner, repo } = context.repo;
            const projectId = process.env.PROJECT_ID;
            const apiKey = process.env.MINTLIFY_API_KEY;

            if (!projectId || !apiKey) {
            core.setFailed('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
            return;
            }

            const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
            const payload = {
            branch: `mintlify/docs-update-${Date.now()}`,
            messages: [
                {
                role: 'system',
                content: 'You are an action runner that updates documentation based on code changes. You should never ask questions. If you are not able to access the repository, report the error and exit.'
                },
                {
                role: 'user',
                content: `Update the documentation for our recent pushes to main:\n\nRepository: ${owner}/${repo}`
                }
            ]
            };

            try {
                const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${apiKey}`,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
                });

                if (!response.ok) {
                throw new Error(`API request failed with status ${response.status}: ${await response.text()}`);
                }

                const reader = response.body.getReader();
                const decoder = new TextDecoder();
                let buffer = '';

                while (true) {
                const { done, value } = await reader.read();
                if (done) break;
                buffer += decoder.decode(value, { stream: true });
                const lines = buffer.split('\n');
                buffer = lines.pop() || '';
                for (const line of lines) {
                    if (line.trim()) {
                    console.log(line);
                    }
                }
                }
                if (buffer.trim()) {
                console.log(buffer);
                }

                core.notice(`Documentation update job triggered for ${owner}/${repo}`);
            } catch (error) {
                core.setFailed(`Failed to create documentation update job: ${error.message}`);
            }

​
Add secrets

  1. In your code repository, go to Settings → Secrets and variables → Actions.
  2. Click New repository secret.
  3. Add the following secrets:
    • Name: MINTLIFY_API_KEY, Secret: Your Mintlify admin API key
    • Name: MINTLIFY_PROJECT_ID, Secret: Your Mintlify project ID (found on the API keys page of your dashboard)
For more information, see Using secrets in GitHub Actions in the GitHub documentation.

​
Test the automation

  1. Make a small change in your code repository and push to main: 
    git add .
git commit -m "Test: trigger docs automation"
git push origin main
  2. Check the Actions tab in your code repository to see the workflow running.
  3. After the workflow runs, check your documentation repository for a new branch and pull request with documentation updates.

​
Troubleshooting

​
Workflow not running

  • Verify GitHub Actions is enabled in your code repository.
  • Check the Actions tab for error messages.
  • Ensure the workflow file is in .github/workflows/ with a .yml extension.

​
401 error from agent API

  • Verify your API key starts with mint_.
  • Check the Authorization header is formatted as Bearer mint_yourkey.
  • Confirm the API key is for the correct Mintlify organization.

​
No documentation updates appearing

  • Check that the documentation repository is connected to your Mintlify project.
  • Verify the agent has write access to the documentation repository.
  • Check the workflow logs for error messages from the agent.