Skip to main content
A custom automation runs the agent on a schedule, on repository pushes, or on connected integration events using instructions that you write. Use a custom automation when you need to automate a task that isn’t covered by a predefined automation. For an overview of triggers, update modes, and configuration options shared across all automations, see Automations.

​
Prerequisites

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

​
Create a custom automation

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 Automations page in your dashboard.
  2. Click Create a custom automation.
  3. Configure the automation name, trigger, instructions, context repositories, integrations, and update mode. For details on each field, see Configurations.
  4. Click Create automation.
You can also ask the agent in Slack to create an automation for you by describing what you want the automation to do.

​
Write effective instructions

Effective automation instructions focus on a single task and define a clear, verifiable outcome. Automations have some variance because agents are nondeterministic, but well-formatted instructions produce more consistent results.
  • Describe the outcome. Tell the agent what a successful run should look like.
  • Write a procedure. Give the agent a step-by-step guide to follow.
  • Keep scope narrow. Split complex tasks across multiple automations rather than combining them into one prompt.
For more examples and patterns, see Use automations.
Review the output of your custom automations to confirm they work as expected. Update your instructions to improve the results.

​
GitLab setup

To use GitLab repositories in an automation, connect each project through the GitLab OAuth settings page. Connect every repository the automation touches—your documentation repository and any trigger or context repositories. You must have at least the Maintainer role on each project.
Automations require a paid GitLab tier. The agent uses short-lived project access tokens for repository access, which GitLab’s Free plan does not support.

​
Bitbucket setup

To use Bitbucket repositories in an automation, connect your Bitbucket account through the Bitbucket OAuth settings in your Mintlify dashboard. Authorize Mintlify to access your Bitbucket workspaces, then select the workspaces and repositories that the automation can use.Mintlify lists repositories where your Bitbucket account has contributor access. Connect the repositories that the automation uses for content, code-change triggers, or context. Mintlify registers a webhook for each connected repository so repository events can trigger automations.Before you configure a connected Bitbucket repository as a deployment Git source, connect that repository in the Bitbucket OAuth settings. Mintlify requires the repository to be part of an active Bitbucket installation before it can use the repository as a Git source.

​
Configure a Bitbucket deployment

  1. Open Git settings in your dashboard, select Connect to Bitbucket, and click Continue.
  2. If Mintlify currently hosts your documentation, click Download to save your content as a zip file. Create a Bitbucket repository, upload the zip contents, and click Continue setup. Connecting your own repository permanently deletes the hosted content, so download it before you continue.
  3. Click Connect Bitbucket and authorize Mintlify to access your workspace and repository.
  4. Enter the Bitbucket workspace slug, repository slug, and deploy branch. If docs.json is in a subdirectory, enable Docs are in a subdirectory and enter the path to the directory containing docs.json.
  5. Click Connect.
For a connected repository configured as a deployment Git source, pushes to the configured branch trigger deployments. Mintlify uses changed files for incremental updates when it can determine the diff. It runs a full update when it cannot determine changed files or when the change affects the entire site.If preview deployments are enabled, pull requests that change documentation content can create preview deployments. Closing a pull request or deleting its source branch removes the matching preview deployment. Merging a pull request cleans up its associated editor branch.Mintlify verifies webhook signatures before processing events. Requests without a valid signature are rejected. Events from unrecognized repositories are ignored.To stop using a repository, disconnect it from the Bitbucket OAuth settings. You can also remove the Bitbucket installation to disconnect all repositories associated with that authorization.

​
Delete a custom automation

Deleting an automation is permanent and removes its configuration and run history.
  1. Open the Automations page in your dashboard.
  2. Click the settings button beside an automation.
  3. Click Delete.