> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial: Auto-update documentation when code changes

> Set up automated documentation updates triggered by code changes using the Mintlify agent API with GitHub Actions or n8n workflow examples.

## What you will build

An automation that updates your documentation when you push code to your main branch. You can build this workflow 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

<Tabs>
  <Tab title="GitHub Actions">
    GitHub Actions is the simplest option if your code is already on GitHub. No additional services required.

    ## GitHub Actions prerequisites

    * GitHub Actions enabled on your code and documentation repositories
    * [Mintlify GitHub App](/deploy/github) installed in both your code and documentation repositories
    * [Mintlify admin API key](https://dashboard.mintlify.com/settings/organization/api-keys)
    * [Mintlify project ID](https://dashboard.mintlify.com/settings/organization/api-keys)
    * [Mintlify Enterprise plan](https://mintlify.com/pricing)
    * Admin access to the GitHub repositories for your code and documentation

    ### Install the Mintlify app on your code repository

    Install the Mintlify app on your code repository so the agent can fetch context from your codebase. To add the app to new repositories:

    1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
    2. Click **Add to New Organization**. This takes you to the app installation page on GitHub.
    3. Select the repositories you want to grant access to from the list.
    4. Save your changes.

    ### Get your admin API key

    1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
    2. Click **Create Admin API Key**.
    3. Copy the key and save it securely.

    ## Build the GitHub Actions workflow

    ### Create the workflow file

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

       ```yaml theme={null}
       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}`
                       }
                     ],
                     asDraft: false
                   };

                   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](https://dashboard.mintlify.com/settings/organization/api-keys) page of your dashboard)

    For more information, see [Using secrets in GitHub Actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) in the GitHub documentation.

    ## Test the GitHub Actions automation

    1. Make a small change in your code repository and push to main:
       ```bash theme={null}
       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.

    ## GitHub Actions troubleshooting

    ### Workflow not running

    * Verify that you enabled GitHub Actions 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 that the Authorization header uses the format `Bearer mint_yourkey`.
    * Confirm the API key is for the correct Mintlify organization.

    ### No documentation updates appearing

    * Check that you connected the documentation repository to your Mintlify project.
    * Verify the agent has write access to the documentation repository.
    * Check the workflow logs for error messages from the agent.
  </Tab>

  <Tab title="n8n">
    n8n provides a visual workflow editor and can integrate with multiple services.

    ## n8n prerequisites

    * n8n workspace
    * [Mintlify Enterprise plan](https://mintlify.com/pricing)
    * Mintlify app installed on your code repository
    * Mintlify admin API key
    * Admin access to the GitHub repositories for your code and documentation
    * GitHub personal access token

    ### Install the Mintlify app on your code repository

    Install the Mintlify app on your code repository so the agent can fetch context from your codebase. To add the app to new repositories:

    1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
    2. Click **Add to New Organization**. This takes you to the app installation page on GitHub.
    3. Select the repositories you want to grant access to from the list.
    4. Save your changes.

    ### Get your admin API key

    1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
    2. Click **Create Admin API Key**.
    3. Copy the key and save it securely.

    ### Get your GitHub personal access token

    1. In GitHub, navigate to **Settings**.
    2. Click **Developer settings**.
    3. Click **Personal access tokens**.
    4. Click **Tokens (classic)**.
    5. Click **Generate new token (classic)**.
    6. Select these scopes:
       * `repo` (full control of private repositories)
       * `admin:repo_hook` (if you want n8n to create webhooks)
    7. Generate and save the token securely.

    For more information, see [Creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\&productId=account-and-profile#creating-a-personal-access-token-classic) in the GitHub documentation.

    ## Build the n8n workflow

    ### Create the webhook trigger

    1. In n8n, create a new workflow.
    2. Add a webhook node.
    3. Configure the webhook:
       * HTTP Method: `POST`
       * Path: `auto-update-documentation` (or any unique path)
       * Authentication: None
       * Respond: Immediately
    4. Save the workflow.
    5. Copy the production webhook URL. It looks like: `https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`

    <Frame>
      <img
        src="https://mintcdn.com/mintlify/MUT1RZiseS3dwdrU/images/guides/n8n/webhook-node.png?fit=max&auto=format&n=MUT1RZiseS3dwdrU&q=85&s=165a57aed92aa90d90609c5d381d29b7"
        alt="Screenshot of the configurations for the webhook node."
        style={{
  width: 'auto',
  height: '700px',
}}
        width="794"
        height="1290"
        data-path="images/guides/n8n/webhook-node.png"
      />
    </Frame>

    ### Set up the GitHub webhook

    1. Navigate to your code repository on GitHub.
    2. Click **Settings**.
    3. Click **Webhooks**.
    4. Click **Add webhook**.
    5. Configure the webhook:
       * Payload URL: Paste your n8n webhook URL
       * Content type: `application/json`
       * Which events would you like to trigger this webhook?
         * Select **Let me select individual events.**
         * Select only **Push events**.
       * Select **Active**
    6. Click **Add webhook**.

    ### Filter for main branch pushes

    Add a code node after the webhook to filter for pushes to main and extract the relevant information.

    1. Add a code node.
    2. Name it "Filter main pushes."
    3. Set mode to **Run Once for All Items**.
    4. Add this JavaScript:

    ```javascript theme={null}
    const webhookData = $input.first().json.body;

    // Only continue if this is a push to main
    if (webhookData.ref !== "refs/heads/main") {
      return [];
    }

    // Extract information
    const repository = webhookData.repository;
    const pusher = webhookData.pusher;

    // Build message for agent
    const agentMessage = `Update documentation for changes pushed to main in ${repository.name}. Always edit files and create a pull request.`;

    return {
      json: {
        codeRepoName: repository.full_name,
        codeRepoShortName: repository.name,
        agentMessage: agentMessage
      }
    };
    ```

    <Frame>
      <img src="https://mintcdn.com/mintlify/MUT1RZiseS3dwdrU/images/guides/n8n/filter-merged-PRs-node.png?fit=max&auto=format&n=MUT1RZiseS3dwdrU&q=85&s=a7661a96b0a5c6272e8a284edb8eb8f5" alt="Screenshot of the configurations for the filter main pushes node." width="1520" height="1444" data-path="images/guides/n8n/filter-merged-PRs-node.png" />
    </Frame>

    This code stops the workflow if the push wasn't to main, extracts all relevant information from the GitHub webhook, and creates a message for the agent API.

    ### Call the agent API

    Add an HTTP request node to create a documentation job.

    1. Add an HTTP request node.
    2. Name it "Create agent job."
    3. Configure the request:

       * Method: `POST`
       * URL: `https://api.mintlify.com/v1/agent/YOUR_PROJECT_ID/job` (replace `YOUR_PROJECT_ID` with your project ID from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page)
       * Authentication: Generic Credential Type → Header Auth
         * Create a new credential:
           * Name: `Authorization`
           * Value: `Bearer mint_YOUR_API_KEY` (replace with your API key)
       * Send Body: On
       * Body Content Type: JSON
       * Specify Body: Using JSON
       * Add this JSON:

       ```json theme={null}
       {
       "branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
       "messages": [
           {
           "role": "system",
           "content": "{{ $json.agentMessage }}"
           }
       ],
       "asDraft": false
       }
       ```

    <Frame>
      <img
        src="https://mintcdn.com/mintlify/jW5VvzJALf7BW1X_/images/guides/n8n/create-agent-job-node.png?fit=max&auto=format&n=jW5VvzJALf7BW1X_&q=85&s=2bbb162905564f80a30bb7d75c917815"
        alt="Screenshot of the configurations for the create agent job node."
        style={{
  width: 'auto',
  height: '700px',
}}
        width="756"
        height="1438"
        data-path="images/guides/n8n/create-agent-job-node.png"
      />
    </Frame>

    The agent creates a pull request in your documentation repository using a descriptive branch name that includes the source repository name and timestamp.

    ### Activate the workflow

    1. Save your workflow.
    2. Set it to active.

    Your workflow is now monitoring your code repository for pushes to main.

    <Frame>
      <img src="https://mintcdn.com/mintlify/MUT1RZiseS3dwdrU/images/guides/n8n/workflow.png?fit=max&auto=format&n=MUT1RZiseS3dwdrU&q=85&s=55120ad3ffc9b32d56aefe05c6431324" alt="Screenshot of the automation workflow in the n8n editor." width="1562" height="632" data-path="images/guides/n8n/workflow.png" />
    </Frame>

    ## Test the n8n automation

    1. Create a test branch in your code repository:
       ```bash theme={null}
       git checkout -b test-docs-automation
       ```

    2. Make a small change and commit it:
       ```bash theme={null}
       git add .
       git commit -m "Test: trigger docs automation"
       git push origin test-docs-automation
       ```

    3. Open a pull request on GitHub.

    4. Merge the pull request.

    ### Verify the automation

    You should see a new n8n execution with all nodes completed successfully, and a new branch and pull request in your documentation repository.

    ## n8n troubleshooting

    ### The webhook is not triggering

    * Verify the workflow is active in n8n.
    * Check GitHub repository Settings → Webhooks → Recent Deliveries for the response code.
    * Confirm the webhook URL matches your n8n webhook URL exactly.

    ### 401 error from agent API

    * Verify your API key starts with `mint_`.
    * Check that the Authorization header uses the format `Bearer mint_yourkey`.
    * Confirm the API key is for the correct Mintlify organization.

    ### 401 error from GitHub

    * Verify your token has the `repo` scope.
    * Check that the token hasn't expired.
    * Confirm you included the `User-Agent` header in the GitHub request.
  </Tab>
</Tabs>


## Related topics

- [Workflows overview](/docs/workflows/index.md)
- [Guides](/docs/guides/index.md)
- [Changelogs](/docs/create/changelogs.md)