Skip to content
Merged
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
6 changes: 4 additions & 2 deletions guides/automate-agent.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
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"]
---

## What you will build

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L8

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 10 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L10

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L10

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 14 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L14

Use 'app' instead of 'application'.

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

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 17 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L17

Use 'app' instead of 'application'.

### Workflow overview

Expand All @@ -41,7 +41,7 @@

### 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 44 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L44

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

1. Open the agent panel in your Mintlify dashboard.
<Frame>
Expand All @@ -53,11 +53,11 @@
<img src="/images/agent/dashboard-settings-light.png" alt="The settings button in light mode." className="block dark:hidden" />
<img src="/images/agent/dashboard-settings-dark.png" alt="The settings button in dark mode." className="hidden dark:block" />
</Frame>
1. Click **Add to New Organization**. This will take you to the app installation page on GitHub.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L56

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

### Get your admin API key

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L60

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 @@ -109,7 +109,8 @@
role: 'user',
content: `Update the documentation for our recent pushes to main:\n\nRepository: ${owner}/${repo}`
}
]
],
asDraft: false
};

try {
Expand Down Expand Up @@ -157,8 +158,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 161 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L161

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 162 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L162

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 @@ -178,17 +179,17 @@
## Troubleshooting

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

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 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 188 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L188

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 192 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L192

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 @@ -203,13 +204,13 @@
- 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 207 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L207

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 213 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L213

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

1. Open the agent panel in your Mintlify dashboard.
<Frame>
Expand All @@ -221,11 +222,11 @@
<img src="/images/agent/dashboard-settings-light.png" alt="The settings button in light mode." className="block dark:hidden" />
<img src="/images/agent/dashboard-settings-dark.png" alt="The settings button in dark mode." className="hidden dark:block" />
</Frame>
1. Click **Add to New Organization**. This will take you to the app installation page on GitHub.

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

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

### Get your admin API key

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 '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 @@ -236,11 +237,11 @@
1. In GitHub, navigate to **Settings**.
2. Click **Developer settings**.
3. Click **Personal access tokens**.
4. Click **Tokens (classic)**.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L240

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L241

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L243

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L244

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 @@ -253,7 +254,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 257 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L257

Use parentheses judiciously.
- Authentication: None
- Respond: Immediately
4. Save the workflow.
Expand All @@ -276,7 +277,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 280 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L280

Avoid first-person pronouns such as 'me'.
- Select only **Push events**.
- Select **Active**
6. Click **Add webhook**.
Expand Down Expand Up @@ -332,7 +333,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 336 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L336

Use parentheses judiciously.
- Send Body: On
- Body Content Type: JSON
- Specify Body: Using JSON
Expand All @@ -346,7 +347,8 @@
"role": "system",
"content": "{{ $json.agentMessage }}"
}
]
],
"asDraft": false
}
```

Expand Down Expand Up @@ -393,7 +395,7 @@

## Troubleshooting

### Webhook not triggering

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L398

'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 @@ -402,7 +404,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 407 in guides/automate-agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/automate-agent.mdx#L407

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