Create a custom workflow

Create a custom Mintlify workflow with a schedule or push trigger, context repositories, and an agent prompt to automate recurring documentation tasks.

Prerequisites

• A Mintlify project connected to a GitHub or GitLab repository
• For GitHub: the Mintlify GitHub App installed on every repository you plan to use in the workflow
• For GitLab: a connected GitLab account (see GitLab setup below)

Create a custom workflow

The agent runs in an isolated sandbox with restricted internet access. It cannot install additional packages or tools at runtime. Prompts that reference unavailable tools may produce unexpected results or fail.

1. Open the Workflows page in your dashboard.
2. Click Create a custom workflow.
3. Configure the workflow name, trigger, instructions, context repositories, and update mode.
4. Click Create workflow.

Write effective instructions

Effective workflow instructions focus on a single task and define a clear, verifiable outcome. Workflows have some variance because agents are nondeterministic, but well formatted instructions produce more consistent results.

• Describe the outcome. Tell the agent what the result should look like of a successful run.
• Write a procedure. Give the agent a step-by-step guide to follow.
• Keep scope narrow. Split complex tasks across multiple workflows rather than combining them into one prompt.

For more examples and patterns, see Use workflows.

Review the output of your custom workflows to confirm they work as expected. Update your instructions to improve the results.

GitLab setup

To use GitLab repositories in a workflow, connect each project through the GitLab OAuth settings page. Connect every repository the workflow touches—your documentation repository and any trigger or context repositories. You must have at least the Maintainer role on each project.

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.

Delete a custom workflow

Deleting a workflow is permanent and removes its configuration and run history.

1. Go to the Workflows page in your dashboard.
2. Click the settings button beside a workflow.
3. Click Delete.