Workflows are in beta. They’re currently free for all plans during the beta period. Workflow features, availability, and pricing are subject to change.
Use workflows that run on a schedule to automate recurring tasks like publishing changelogs or checking for grammar and style issues.Use workflows that run on push events to automate reactive maintenance tasks like updating API references or identifying documentation updates needed for new features.
Create a workflow
Create a workflow in the dashboard
- Open the Workflows page.
- Click New workflow.
- Configure the trigger, prompt, and other settings.
- Optionally, enable Slack notifications to notify channels when the workflow completes. See Slack notifications.
- Click Create workflow.
Create a workflow file with the CLI
If you have the Mintlify CLI installed, run the following command from your documentation repository to create a workflow file interactively in the CLI.
The CLI prompts you for information about the workflow and creates a .md file in the .mintlify/workflows/ directory. Commit and push the file to activate the workflow.
If you run mint workflow in a non-interactive environment such as a CI/CD pipeline or an AI coding agent, the CLI returns usage instructions and the workflow file format instead of interactive prompts.
Add a workflow file to your repository
Create a .md file for each workflow in a .mintlify/workflows/ directory at the root of your documentation repository. Each file defines one workflow.
If you have a monorepo, place the .mintlify/workflows/ folder inside your documentation root directory where your docs.json file is, not at the repository root.
.mintlify/workflows/update-changelog.md
---
name: Update changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
---
Review all changes since the last changelog update. Draft a new changelog post with any new features, bug fixes, or breaking changes.
Include information about what a change is and how it affects users.
Do not include any internal-only information or minor changes like bumping package versions or updating documentation.
Success criteria: Someone who reads the changelog knows the most up to date information about the product including what changed and whether or not it affects them.
Frontmatter fields
| Field | Required | Description |
|---|
name | Yes | Display name shown in the dashboard. |
on | Yes | Trigger configuration. |
context | No | Repositories cloned as reference when the workflow runs. |
automerge | No | Defaults to false, which opens a pull request for review. If true, opens a pull request and automatically merges it. |
notify | No | Notification configuration. Send Slack messages when workflows complete. |
context or on.push.repo fields. Add new repositories on the GitHub app page of your Mintlify dashboard.
Triggers
Each workflow must define exactly one trigger using the on field.
On schedule (cron)
Run a workflow on a recurring schedule using a cron expression. All schedules run in UTC.
Workflows queue within 10 minutes of the scheduled time and may take up to 10 minutes to run.
The value is a standard 5-field cron expression in minute hour day-of-month month day-of-week format. Use a tool like crontab.guru to build and validate schedules.
| Expression | Schedule |
|---|
"0 9 * * 1" | Every Monday at 9:00 AM UTC |
"0 0 1 * *" | First day of each month at midnight UTC |
"0 8 * * 1-5" | Weekdays at 8:00 AM UTC |
On push events
Run a workflow when changes push to a specific repository or branch. This includes both pull request merges and direct pushes to the branch.
on:
push:
- repo: your-org/your-product
branch: main
repo: The GitHub repository in owner/repo format.branch (optional): The branch to watch for pushes. If you don’t specify a branch, the workflow triggers on pushes to the repository’s default branch.
A workflow can watch for pushes to multiple repositories or branches.
on:
push:
- repo: your-org/your-product
- repo: your-org/another-repo
branch: release
Context repositories
Use context to give the agent read access to additional repositories when the workflow runs. This is useful when your prompt requires reviewing code or content outside your documentation repository.
context:
- repo: your-org/your-product
- repo: your-org/design-system
Auto-merge changes
By default, the agent opens a pull request for each workflow run so you can review changes before they go live. Set automerge: true to automatically merge the pull request without requiring manual approval. This gives you a record of changes in your repository’s pull request history while automating the merge step.
Slack notifications
Send Slack messages when a workflow completes or fails. Notifications include the workflow status, a link to the pull request, and a summary of the changes.
Slack notifications require a Slack installation on your organization. Connect Slack on your dashboard.
- Toggle Notify on completion to enable Slack notifications.
- Search for and select the channels you want to notify.
- Save your workflow.
Use the notify field to configure Slack notifications in a workflow file:
notify:
slack:
channels:
- documentation
- dev-updates
users:
- alice
- bob
| Field | Description |
|---|
channels | Channel names to notify (with or without # prefix). |
channel_ids | Channel IDs to notify. |
users | Usernames, display names, or real names to DM. |
user_ids | Slack user IDs to DM. |
Prompts
Effective prompts focus on one task and have a specific outcome in mind. Workflows always have some variance because of the nondeterministic nature of agents, but you can improve the consistency of workflow outputs by following these best practices.
- Describe the outcome you want the agent to achieve.
- Include success criteria.
- Specify the context you want the agent to use.
- Split complex tasks into steps or multiple workflows.
Agent environment
The agent runs in an isolated sandbox with restricted internet access. When writing prompts, only reference tools available to the agent.
- Standard shell utilities (
grep, sed, awk, curl, and others)
git and the GitHub CLI (gh)- The Mintlify CLI (
mint)
- Node.js and Bun
The agent cannot install additional packages or tools at runtime. Package registries and other external services are not reachable from the sandbox.
Prompts that instruct the agent to run unavailable tools may produce unexpected results or fail.
Example workflows
Draft documentation for new features
If you use agent suggestions in your dashboard, this workflow replicates that behavior.Add this workflow with any modifications for your project to automatically draft documentation as you add new features to your product.
.mintlify/workflows/draft-feature-docs.md
---
name: Draft docs for new features
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
Review the diff from the last merged PR in `your-org/your-product`. Identify any new features, APIs, or other changes that require documentation.
For each new addition, draft documentation updates that explain what it does, when to use it, and how to configure it. Include a code example where relevant.
Success criteria: After reading any new or updated documentation, users understand what the feature is, if it applies to tasks they do, and how to use it.
## Important
- Only document changes that affect end users. Skip internal refactors or dependency updates.
- Match the style and structure of existing docs pages.
Style audit
Runs when changes push to your documentation repository to catch style guide violations before they accumulate. This example workflow automatically fixes style guide violations and lists any violations that require human judgment in the PR body.
.mintlify/workflows/style-audit.md
---
name: Style audit
on:
push:
- repo: your-org/your-docs
branch: main
automerge: false
---
Review all MDX files changed in the last merged PR against the style guide at `path/to/style-guide`.
Open a pull request to resolve any style violations that can be fixed automatically. For any edits that require judgment or nuance, note them in the PR body with the specific lines, rule violations, and suggested fixes.
Success criteria:
- All style violations have a proposed resolution.
- No new style violations are introduced.
## Important
- Do not change content meaning. Only correct style violations.
- Skip any files in language subdirectories (`es/`, `fr/`, `zh/`).
Update API reference
Runs when pull requests merge to your product repository to keep API reference pages in sync with your product code. When endpoints or parameters change, this workflow updates the corresponding content in your documentation.
.mintlify/workflows/update-api-reference.md
---
name: Update API reference
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
Review the diff from the last merged PR in `your-org/your-product` for changes to API endpoints, parameters, response shapes, or error codes.
Update the corresponding API specifications or pages in the docs to reflect the changes. Include updated parameter descriptions, type information, and examples where affected.
Success criteria: All API specifications and pages are up to date with the changes in the product repository.
## Important
- If a parameter or endpoint was removed, mark it as deprecated rather than deleting it unless the code explicitly removes it with no deprecation period.
- If no API changes were introduced, do nothing.
Track translation lag
Run weekly to compare English source files against their translations and identify pages that have fallen behind.
To use this workflow, update the example language subdirectories (es/, fr/, zh/) to your actual language subdirectories.
.mintlify/workflows/translation-lag.md
---
name: Track translation lag
on:
cron: "0 9 * * 3"
---
Compare the English MDX files in the repo against their counterparts in the `es/`, `fr/`, and `zh/` subdirectories. Use git history to identify English files updated more recently than their translations.
Open a pull request that lists pages that are out of sync, organized by language. For each page, include the date of the last English update and a brief summary of what changed so translators have context on what to update.
Success criteria: Any discrepancies between the English and translated files are identified and listed in the pull request.
## Important
- If a translated file does not exist, flag it as missing rather than out of sync.
- Group findings by language, then by how far out of date they are (most stale first).
description frontmatter. Edit the workflow to check for other metadata or content issues that you prioritize for your documentation.
.mintlify/workflows/seo-audit.md
---
name: SEO and metadata audit
on:
cron: "0 9 * * 1"
automerge: false
---
Audit all MDX files in the docs for SEO and metadata quality. Check for:
- Missing or empty `description` frontmatter
- Descriptions that are too short (under 50 characters) or too long (over 160 characters)
Open a pull request with improvements for any issues found. Write descriptions that accurately summarize the page content in plain language.
Success criteria: All pages have up to date descriptions that accurately summarize the page content in plain language.
## Important
- Only update frontmatter. Do not change page content.
- If all pages have complete and reasonable metadata, do nothing.
Changelog with notifications
Runs weekly to generate a changelog and notify your team on Slack when the workflow completes. This example shows how to combine scheduled workflows with Slack notifications.
.mintlify/workflows/changelog-with-notify.md
---
name: Weekly changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
notify:
slack:
channels:
- documentation
users:
- tech-writer
---
Review all merged PRs in `your-org/your-product` from the past week. Draft a changelog entry summarizing new features, bug fixes, and breaking changes.
Success criteria: The changelog accurately reflects the week's changes and is ready for review.
