Skip to main content

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.

Workflows run the agent automatically so your content stays accurate without manual effort. This guide covers how to choose the right workflow, configure it effectively, and write instructions that produce consistent results.

​
When to use workflows

Workflows are best for tasks that are:
  • Repetitive — The same task runs regularly on a predictable schedule or whenever a specific event occurs.
  • Time-consuming — Tasks that take time to do manually but follow a consistent pattern.
  • Reactive — Tasks that should happen automatically in response to code or content changes, like updating docs after a feature ships.
For one-off or exploratory tasks, use the agent directly in the dashboard or from Slack.

​
Choose a trigger

Each workflow runs on one of three trigger types. Choose the one that matches when you need the work done.
TriggerUse when
Content updateThe task should run whenever your project content changes—translating new pages, fixing broken links, or auditing SEO metadata.
Code changeThe task should run when source code changes—updating API specifications or documentation after a PR merges.
Custom scheduleThe task should run on a fixed cadence regardless—publishing weekly changelogs or running periodic grammar checks.

​
Predefined workflows

Mintlify includes predefined workflows for the most common content maintenance tasks. Toggle any of them on from the Workflows page of your dashboard. See Predefined workflows for more details.

​
Custom workflows

Create a custom workflow for tasks that aren’t covered by the predefined options. Custom workflows give you full control over the trigger, instructions, and context repositories. See Create a custom workflow for setup steps.

​
Write effective instructions

Custom workflow instructions are prompts the agent follows on every run. The quality of your instructions directly affects the consistency of results. Describe the outcome, not just the task. Tell the agent what done looks like. 
Review the API reference pages.
Write a procedure. Agents follow step-by-step instructions more reliably than open-ended prompts.
Example procedure
1. Read the merged pull request diff from the trigger repository.
2. Identify any changed API endpoints, parameters, or response shapes.
3. Search the documentation for pages that reference those endpoints.
4. Update the affected pages to match the changes in the pull request.
5. Open a pull request with a summary of the pages you changed and why.
Keep scope narrow. A workflow that does one thing well is more reliable than one that tries to do many things. Split complex tasks across multiple workflows. Specify files and directories. The more precise you are about where the agent should look, the less time it spends searching.
Example with specific paths
Check every MDX file in the /content directory for broken internal links (links beginning with /). 
For each broken link, either fix the path or remove the link if no replacement exists.

​
Use context repositories

For custom workflows and some predefined workflows, you can add context repositories the agent reads when the workflow runs. Add context repositories when:
  • Your content references code, APIs, or configuration that lives in a separate repository.
  • You want the agent to compare your content against source code when deciding what to update.
  • The workflow prompt refers to files outside your Mintlify project repository.
You can add up to 10 context repositories per workflow.

​
Update mode

Decide how much review you want before changes go live.
  • Automatic: Changes merge directly into your Mintlify project repository without review. Best for low-risk, high-frequency tasks like translation, grammar checks, and link fixes.
  • Require review: The agent opens a pull request and a human reviews it before merging. Best for tasks that change content meaning, like syncing with code changes or updating API references.

​
Control credit usage

Every workflow run consumes credits. For example, most update from code changes workflow runs cost between 40 and 180 credits. Complex runs that update many pages cost more. Scheduling cron jobs to run at specific times gives you more precise control over credit usage. For example, run a workflow once a day or once a week to know exactly how many pull requests it creates per month. Push-triggered workflows can vary more from month to month because they depend on how often content or code changes.

​
Review and improve workflow results

Workflows run automatically, but they benefit from periodic review.
  1. Open the Runs tab on the Workflows page to see recent run history and status.
  2. Click a run to read the agent’s summary and review any pull requests it opened.
  3. If results are inconsistent, refine your instructions: add more specific procedures, narrow the file scope, or split the workflow into smaller tasks.
A few review cycles after enabling a new workflow are usually enough to dial in the instructions.

Related topics

Workflows overviewGuidesTooltips