Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions guides/automate-agent.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,24 @@
---
title: "Tutorial: Auto-update documentation when code is changed"

Check warning on line 2 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L2

In general, use active voice instead of passive voice ('is changed').
sidebarTitle: "Automate documentation updates"
description: "Use the agent API to automatically update your documentation."
keywords: ["agent automation", "n8n", "GitHub Actions", "automatic doc updates"]
---

<Warning>
**Known issue**: Document `.mintignore` feature - agent encountered `AI_APICallError: Bad Request` when listing files from external repository. Reference: Slack thread #C03SJRBUH8X (reported by @U094K8T8423, @U07UV85Q5QU, @U094WVDUF7F).

Check warning on line 9 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L9

': D' should be in lowercase.

Check warning on line 9 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L9

': S' should be in lowercase.

Check warning on line 9 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L9

Use parentheses judiciously.
</Warning>

## What you will build

Check warning on line 12 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L12

Avoid using 'will'.

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.

Check warning on line 14 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L14

In general, use active voice instead of passive voice ('is pushed').

Check warning on line 14 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L14

In general, use active voice instead of passive voice ('be built').

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.

Check warning on line 18 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L18

Use 'app' instead of 'application'.

Check warning on line 18 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L18

Use 'command-line tool' instead of 'CLI'.
- **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.

Check warning on line 21 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L21

Use 'app' instead of 'application'.

### Workflow overview

Expand All @@ -41,14 +45,14 @@

### Install the Mintlify app on your code repository

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

Check warning on line 48 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L48

In general, use active voice instead of passive voice ('be installed').

1. Navigate to the [Agent](https://dashboard.mintlify.com/products/agent) page in your Mintlify dashboard.
2. Click **Add to new organization**. This will take you to the app installation page on GitHub.

Check warning on line 51 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L51

Avoid using 'will'.
3. Select the repositories you want to grant access to from the list.
4. Save your changes.

### Get your admin API key

Check warning on line 55 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L55

Use 'administrator' instead of 'admin'.

1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
2. Select **Create Admin API Key**.
Expand Down Expand Up @@ -148,8 +152,8 @@
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

Check warning on line 155 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L155

Use 'administrator' instead of 'admin'.
- 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)

Check warning on line 156 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L156

Use parentheses judiciously.

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.

Expand All @@ -169,17 +173,17 @@
## Troubleshooting

### Workflow not running
- Verify GitHub Actions is enabled in your code repository.

Check warning on line 176 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L176

In general, use active voice instead of passive voice ('is enabled').
- 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`.

Check warning on line 182 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L182

In general, use active voice instead of passive voice ('is formatted').
- 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.

Check warning on line 186 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L186

In general, use active voice instead of passive voice ('is connected').
- Verify the agent has write access to the documentation repository.
- Check the workflow logs for error messages from the agent.

Expand All @@ -194,20 +198,20 @@
- n8n workspace
- [Mintlify Pro or Custom plan](https://mintlify.com/pricing)
- Mintlify app installed on your code repository
- Mintlify admin API key

Check warning on line 201 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L201

Use 'administrator' instead of 'admin'.
- Admin access to the GitHub repositories for your code and documentation
- GitHub personal access token

### Install the Mintlify app on your code repository

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

Check warning on line 207 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L207

In general, use active voice instead of passive voice ('be installed').

1. Navigate to the [Agent](https://dashboard.mintlify.com/products/agent) page in your Mintlify dashboard.
2. Click **Add to new organization**. This will take you to the app installation page on GitHub.

Check warning on line 210 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L210

Avoid using 'will'.
3. Select the repositories you want to grant access to from the list.
4. Save your changes.

### Get your admin API key

Check warning on line 214 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L214

Use 'administrator' instead of 'admin'.

1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
2. Select **Create Admin API Key**.
Expand All @@ -218,11 +222,11 @@
1. In GitHub, navigate to **Settings**.
2. Click **Developer settings**.
3. Click **Personal access tokens**.
4. Click **Tokens (classic)**.

Check warning on line 225 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L225

Use parentheses judiciously.
5. Click **Generate new token (classic)**.

Check warning on line 226 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L226

Use parentheses judiciously.
6. Select these scopes:
- `repo` (full control of private repositories)

Check warning on line 228 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L228

Use parentheses judiciously.
- `admin:repo_hook` (if you want n8n to create webhooks)

Check warning on line 229 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L229

Use parentheses judiciously.
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.
Expand All @@ -235,7 +239,7 @@
2. Add a webhook node.
3. Configure the webhook:
- HTTP Method: `POST`
- Path: `auto-update-documentation` (or any unique path)

Check warning on line 242 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L242

Use parentheses judiciously.
- Authentication: None
- Respond: Immediately
4. Save the workflow.
Expand All @@ -258,7 +262,7 @@
- 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.**

Check warning on line 265 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L265

Avoid first-person pronouns such as 'me'.
- Select only **Push events**.
- Select **Active**
6. Click **Add webhook**.
Expand Down Expand Up @@ -314,7 +318,7 @@
- Authentication: Generic Credential Type → Header Auth
- Create a new credential:
- Name: `Authorization`
- Value: `Bearer mint_YOUR_API_KEY` (replace with your API key)

Check warning on line 321 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L321

Use parentheses judiciously.
- Send Body: On
- Body Content Type: JSON
- Specify Body: Using JSON
Expand Down Expand Up @@ -375,7 +379,7 @@

## Troubleshooting

### Webhook not triggering

Check warning on line 382 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L382

'Webhook not triggering' should use sentence-style capitalization.

- Verify the workflow is active in n8n.
- Check GitHub repository Settings → Webhooks → Recent Deliveries for the response code.
Expand All @@ -384,7 +388,7 @@
### 401 error from agent API

- Verify your API key starts with `mint_`.
- Check the Authorization header is formatted as `Bearer mint_yourkey`.

Check warning on line 391 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L391

In general, use active voice instead of passive voice ('is formatted').
- Confirm the API key is for the correct Mintlify organization.

### 401 error from GitHub
Expand Down