Set up automated documentation workflows with scheduled or event-triggered agent tasks, including cron schedules and webhook-based automation.
Workflows are in beta. They’re currently free for all plans during the beta period. Workflow features, availability, and pricing are subject to change.
Workflows run the agent automatically on a schedule or on a push to a repository. Each workflow defines a prompt for the agent and a trigger for when to run it. Workflows support both GitHub and GitLab repositories.When a workflow runs, the agent clones any specified repositories as context, follows the prompt, and either opens a pull request (or merge request for GitLab) or pushes changes directly to your deployment branch.Each workflow can run up to 50 times a day. Runs that fail do not count toward this limit.
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.
Repositories cloned as reference when the workflow runs.
Automerge
No
Defaults to off, which opens a pull request for review. If enabled, opens a pull request and automatically merges it.
Notify
No
Notification configuration. Send Slack messages when workflows complete.
For GitHub repositories, you must have the Mintlify GitHub App installed on every repository listed in the context or trigger fields. Add new repositories on the GitHub app page of your Mintlify dashboard.For GitLab repositories, you must connect your GitLab account on the GitLab OAuth page in your Mintlify dashboard. Then add the repositories you want to use with workflows. You must have at least the Maintainer role on each project to connect GitLab OAuth .
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.
Run a workflow when changes push to a specific repository or branch. This includes both pull request merges and direct pushes to the branch.Specify each repository in owner/repo format. Optionally specify a branch to watch. 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 up to 10 repositories or branches.
Context repositories 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. You can specify up to five context repositories per workflow.
By default, the agent opens a pull request for each workflow run so you can review changes before they go live. Enable auto-merge 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.
For GitHub repositories, automerge requires the Mintlify GitHub App to have bypass permissions on all rulesets that target your deploy branch, including organization-level and repository-level rulesets. See Configure automerge for setup instructions.For GitLab repositories, automerge uses the GitLab OAuth connection configured on the GitLab OAuth page of your Mintlify dashboard. You must have at least the Maintainer role on each project to connect GitLab OAuth .
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 the Mintlify Slack app in your organization’s Slack workspace. Install the Slack app from your dashboard.
When creating or editing a workflow in the dashboard, enable Slack notifications under the Notify on completion toggle:
If you haven’t connected Slack, click Install Slack app.
Click the Notify on completion toggle.
Search for and select the channels you want to notify.
Disable a workflow to temporarily stop it from running without deleting it. Disabled workflows keep their configuration and run history, but do not execute on their schedule or in response to push events. You cannot manually trigger a disabled workflow.To toggle a workflow:
To use GitLab repositories in a workflow, connect each project through the GitLab OAuth integration on the GitLab OAuth settings page. You must connect every repository the workflow touches, including your documentation repository and any trigger or context repositories.
Workflows require a paid GitLab tier. The agent uses short-lived project access tokens for repository access, which GitLab’s Free plan does not support.
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.
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.
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.
Trigger: On push to your-org/your-product (main branch)
Context repos:your-org/your-docs
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.
Trigger: On push to your-org/your-docs (main branch)
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/`).
Trigger: On push to your-org/your-product (main branch)
Context repos:your-org/your-docs
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.
Trigger: Cron schedule 0 9 * * 3 (Wednesdays at 9:00 AM UTC)Update the example language subdirectories (es/, fr/, zh/) to your actual language subdirectories.
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).
Trigger: Cron schedule 0 9 * * 1 (Mondays at 9:00 AM UTC)
Audit all MDX files in the docs for SEO and metadata quality. Check for:- Missing or empty `title` frontmatter- Titles that are too long (over 60 characters) — long titles are truncated in search result snippets- Titles that follow a boilerplate pattern like "PageType - Name" without describing the specific content of the page- Missing or empty `description` frontmatter (see OpenAPI pages below — do not treat as missing when an OpenAPI spec supplies the description)- Descriptions that are too short (under 130 characters) — short descriptions are frequently ignored by Google in favor of auto-generated snippets- Descriptions that are too long (over 160 characters)- Pages that share an identical description with other pages — each page needs a unique descriptionOpen a pull request with improvements for any issues found.When writing titles: be descriptive and specific about what the page covers. Avoid generic patterns like "Overview - Product Name". Target 50-60 characters.When writing descriptions: summarize what the specific page covers in plain language. Include 2-3 terms a user would actually search for. Never reuse the same description across pages. Target 130-155 characters.### Pages with `openapi:` in frontmatter (API reference from spec)The `openapi:` frontmatter value can be either an **operation reference** (e.g., `openapi: GET /users/{id}`) or a **file reference** (e.g., `openapi: ./openapi.yaml`). Only operation references supply per-page `summary` and `description` from the spec.For pages with an **operation reference**:- Read the referenced OpenAPI spec file to check whether the operation defines a `description`.- If the operation **has** a `description`: do not add a `description:` field to frontmatter. If one was incorrectly added, remove it so the metadata comes from the spec.- If the operation **has no** `description`: audit `description` frontmatter as normal — add one if missing or fix it if it fails the quality checks.- If the operation defines a `summary` and the page has no `title:` frontmatter, treat the title as present — do not add one.- Never edit the OpenAPI spec files themselves.For pages with a **file reference**, audit all frontmatter fields as normal.Success criteria:- Pages have a unique title under 60 characters that describes the specific content- Pages have a unique description between 130 and 160 characters (except for pages where the OpenAPI spec supplies the description)## Important- Only update frontmatter. Do not change page content or OpenAPI spec files.- If all pages have complete and reasonable metadata, do nothing.
Trigger: Cron schedule 0 9 * * 1 (Mondays at 9:00 AM UTC)
Context repos:your-org/your-productSlack notifications:documentation channel, tech-writer user
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.
