> ## Documentation Index
> Fetch the complete documentation index at: https://tomee-mintlify-bitbucket-oauth-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom automation

> Create a Mintlify automation that runs on a schedule, repository push, or integration event. Add context repositories and a custom agent prompt.

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](/automations/reference).

For an overview of triggers, update modes, and configuration options shared across all automations, see [Automations](/automations).

## Prerequisites

* A Mintlify project connected to a GitHub, GitLab, or Bitbucket repository
* For GitHub: the [Mintlify GitHub App](/deploy/github) installed on every repository you plan to use in the automation
* For GitLab: a connected GitLab account (see [GitLab setup](#gitlab-setup) below)
* For Bitbucket: a connected Bitbucket account (see [Bitbucket setup](#bitbucket-setup) below)

## Create a custom automation

<Note>
  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.
</Note>

1. Open the [Automations](https://app.mintlify.com/products/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](/automations/manage#configurations).
4. Click **Create automation**.

<Tip>
  You can also ask the [agent in Slack](/agent/slack#manage-automations) to create an automation for you by describing what you want the automation to do.
</Tip>

## 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](/guides/use-automations).

<Tip>
  Review the output of your custom automations to confirm they work as expected. Update your instructions to improve the results.
</Tip>

## GitLab setup

To use GitLab repositories in an automation, connect each project through the [GitLab OAuth](https://app.mintlify.com/settings/organization/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.

<Note>
  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.
</Note>

<div id="bitbucket-setup">
  ## 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](https://app.mintlify.com/settings/deployment/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.
</div>

## Delete a custom automation

Deleting an automation is permanent and removes its configuration and run history.

1. Open the [Automations](https://app.mintlify.com/products/automations) page in your dashboard.
2. Click the <Icon icon="settings" /> settings button beside an automation.
3. Click **Delete**.