Skip to content

Remove Workflow Files #5397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paaatrrrick wants to merge 3 commits into
base: main
Choose a base branch
from
+36 −247
Open

Remove Workflow Files #5397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
29426ee
Remove Workflow Files
paaatrrrick Apr 15, 2026
ec58cd4
Merge branch 'main' into patrick/remove-workflow-files
ethanpalm Apr 16, 2026
f629db2
Apply suggestions from code review
ethanpalm Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 36 additions & 193 deletions agent/workflows.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@

## Create a workflow

### Create a workflow in the dashboard

1. Open the [Workflows](https://dashboard.mintlify.com/products/workflows) page.
2. Click **New workflow**.
3. Configure the workflow name, trigger type, repositories, and schedule.
Expand All @@ -37,60 +35,17 @@
<img src="/images/agent/new-workflow-dark.png" alt="The new workflow setup page." className="hidden dark:block" />
</Frame>

### Create a workflow file with the CLI

If you have the [Mintlify CLI](/cli) installed, run the following command from your documentation repository to create a workflow file interactively in the CLI.

```bash
mint workflow
```

The CLI prompts you for information about the workflow and creates a `.md` file in the `.mintlify/workflows/` directory. Commit and push the file to activate the workflow.

<Tip>
If you run `mint workflow` in a non-interactive environment such as a CI/CD pipeline or an AI coding agent, the CLI returns usage instructions and the workflow file format instead of interactive prompts.
</Tip>

### Add a workflow file to your repository

Create a `.md` file for each workflow in a `.mintlify/workflows/` directory at the root of your documentation repository. Each file defines one workflow.

<Note>
If you have a monorepo, place the `.mintlify/workflows/` folder inside your documentation root directory where your `docs.json` file is, not at the repository root.
</Note>

Workflow files use YAML frontmatter to configure the workflow, followed by a Markdown prompt for the agent.

```markdown .mintlify/workflows/update-changelog.md
---
name: Update changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
---

Review all changes since the last changelog update. Draft a new changelog post with any new features, bug fixes, or breaking changes.

Include information about what changed and how it affects users.

Do not include any internal-only information or minor changes like bumping package versions or updating documentation.

Success criteria: Someone who reads the changelog knows the most up to date information about the product including what changed and whether or not it affects them.
```

## Frontmatter fields
## Configuration

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Display name shown in the dashboard. |
| `on` | Yes | Trigger configuration. |
| `context` | No | Repositories cloned as reference when the workflow runs. |
| `automerge` | No | Defaults to `false`, which opens a pull request for review. If `true`, opens a pull request and automatically merges it. |
| `notify` | No | Notification configuration. Send Slack messages when workflows complete. |
| **Name** | Yes | Display name shown in the dashboard. |
| **Trigger** | Yes | Trigger configuration. |
| **Context** | No | 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 `on.push.repo` fields. Add new repositories on the [GitHub app](https://dashboard.mintlify.com/settings/organization/github-app) page of your Mintlify dashboard.
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](https://dashboard.mintlify.com/settings/organization/github-app) page of your Mintlify dashboard.

For GitLab repositories, you must connect your GitLab account on the [GitLab OAuth](https://dashboard.mintlify.com/settings/organization/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 .

Expand All @@ -101,75 +56,44 @@

### Triggers

Each workflow must define exactly one trigger using the `on` field.
Each workflow must define exactly one trigger.

#### On schedule (cron)

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.

```yaml
on:
cron: "0 9 * * 1"
```

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](https://crontab.guru) to build and validate schedules.

| Expression | Schedule |
|------------|----------|
| `"0 9 * * 1"` | Every Monday at 9:00 AM UTC |
| `"0 0 1 * *"` | First day of each month at midnight UTC |
| `"0 8 * * 1-5"` | Weekdays at 8:00 AM UTC |
| `0 9 * * 1` | Every Monday at 9:00 AM UTC |
| `0 0 1 * *` | First day of each month at midnight UTC |
| `0 8 * * 1-5` | Weekdays at 8:00 AM UTC |

#### On push events

Run a workflow when changes push to a specific repository or branch. This includes both pull request merges and direct pushes to the branch.

```yaml
on:
push:
- repo: your-org/your-product
branch: main
```

- `repo`: The repository in `owner/repo` format.
- `branch` (optional): The branch to watch for pushes. If you don't specify a branch, the workflow triggers on pushes to the repository's default 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.

```yaml
on:
push:
- repo: your-org/your-product
- repo: your-org/another-repo
branch: release
```

### Context repositories

Use `context` to 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.

```yaml
context:
- repo: your-org/your-product
- repo: your-org/design-system
```
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.

### Auto-merge changes

By default, the agent opens a pull request for each workflow run so you can review changes before they go live. Set `automerge: true` 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.
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.

<Note>
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](/guides/configure-automerge) for setup instructions.

For GitLab repositories, automerge uses the GitLab OAuth connection configured on the [GitLab OAuth](https://dashboard.mintlify.com/settings/organization/gitlab-oauth) page of your Mintlify dashboard. You must have at least the Maintainer role on each project to connect GitLab OAuth .
</Note>

```yaml
automerge: true
```

### Slack notifications

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.
Expand All @@ -178,44 +102,16 @@
Slack notifications require the Mintlify Slack app in your organization's Slack workspace. Install the Slack app from your [dashboard](https://dashboard.mintlify.com/products/agent).
</Note>

#### Configure Slack notifications in the dashboard

When creating or editing a workflow in the dashboard, you can enable Slack notifications under the **Notify on completion** toggle:
When creating or editing a workflow in the dashboard, enable Slack notifications under the **Notify on completion** toggle:

1. If you haven't connected Slack, click **Install Slack app**.
2. Click the **Notify on completion** toggle.
3. Search for and select the channels you want to notify.
4. Save your workflow.

#### Configure Slack notifications in workflow files

Use the `notify` field to configure Slack notifications in a workflow file:

```yaml
notify:
slack:
channels:
- documentation
- dev-updates
users:
- alice
- bob
```

You can specify notification targets by name or by ID:

| Field | Description |
|-------|-------------|
| `channels` | Channel names to notify (with or without `#` prefix). |
| `channel_ids` | Channel IDs to notify. |
| `users` | Usernames, display names, or real names to DM. |
| `user_ids` | Slack user IDs to DM. |

## Manage workflows

If you create a workflow in the dashboard, edit or delete it from the dashboard.

If you create a workflow from a file in your repository, edit or delete it with a pull request modifying the file.
Edit, delete, disable, or trigger workflows from the [Workflows](https://dashboard.mintlify.com/products/workflows) page in your dashboard.

### Trigger a workflow manually

Expand Down Expand Up @@ -268,7 +164,9 @@

Prompts that instruct the agent to run unavailable tools may produce unexpected results or fail.

## Example workflows
## Example prompts

These example prompts demonstrate common workflow patterns. Create a workflow in the dashboard and paste the prompt into the instructions field.

### Draft documentation for new features

Expand All @@ -278,20 +176,10 @@
Add this workflow with any modifications for your project to automatically draft documentation as you add new features to your product.
</Tip>

Runs when you push changes to your product repository to identify documentation updates needed for any new features or APIs.

```markdown .mintlify/workflows/draft-feature-docs.md
---
name: Draft docs for new features
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
**Trigger:** On push to `your-org/your-product` (main branch)
**Context repos:** `your-org/your-docs`

```text
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.
Expand All @@ -306,18 +194,9 @@

### Style audit

Runs when changes push to your documentation repository to catch style guide violations before they accumulate. This example workflow automatically fixes style guide violations and lists any violations that require human judgment in the PR body.

```markdown .mintlify/workflows/style-audit.md
---
name: Style audit
on:
push:
- repo: your-org/your-docs
branch: main
automerge: false
---
**Trigger:** On push to `your-org/your-docs` (main branch)

```text
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.
Expand All @@ -334,23 +213,13 @@

### Update API reference

Runs when pull requests merge to your product repository to keep API reference pages in sync with your product code. When endpoints or parameters change, this workflow updates the corresponding content in your documentation.

```markdown .mintlify/workflows/update-api-reference.md
---
name: Update API reference
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
**Trigger:** On push to `your-org/your-product` (main branch)
**Context repos:** `your-org/your-docs`

```text
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.

Check warning on line 222 in agent/workflows.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/workflows.mdx#L222 

Did you really mean 'informat'?

Success criteria: All API specifications and pages are up to date with the changes in the product repository.

Expand All @@ -362,17 +231,11 @@

### Track translation lag

Run weekly to compare English source files against their translations and identify pages that have fallen behind.
**Trigger:** Cron schedule `0 9 * * 3` (Wednesdays at 9:00 AM UTC)

Check warning on line 234 in agent/workflows.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/workflows.mdx#L234 

Use 'cron' instead of 'Cron'.

To use this workflow, update the example language subdirectories (`es/`, `fr/`, `zh/`) to your actual language subdirectories.

```markdown .mintlify/workflows/translation-lag.md
---
name: Track translation lag
on:
cron: "0 9 * * 3"
---
Update the example language subdirectories (`es/`, `fr/`, `zh/`) to your actual language subdirectories.

```text
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.
Expand All @@ -387,16 +250,9 @@

### SEO and metadata audit

Runs weekly to check for pages with missing or weak metadata and open a pull request with improvements. This example workflow checks for missing, weak, or duplicate `title` and `description` frontmatter and flags boilerplate patterns. Edit the workflow to check for other metadata or content issues that you prioritize for your documentation.

```markdown .mintlify/workflows/seo-audit.md
---
name: SEO and metadata audit
on:
cron: "0 9 * * 1"
automerge: false
---
**Trigger:** Cron schedule `0 9 * * 1` (Mondays at 9:00 AM UTC)

Check warning on line 253 in agent/workflows.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/workflows.mdx#L253 

Use 'cron' instead of 'Cron'.

```text
Audit all MDX files in the docs for SEO and metadata quality. Check for:

- Missing or empty `title` frontmatter
Expand Down Expand Up @@ -438,24 +294,11 @@

### Changelog with notifications

Runs weekly to generate a changelog and notify your team on Slack when the workflow completes. This example shows how to combine scheduled workflows with Slack notifications.

```markdown .mintlify/workflows/changelog-with-notify.md
---
name: Weekly changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
notify:
slack:
channels:
- documentation
users:
- tech-writer
---
**Trigger:** Cron schedule `0 9 * * 1` (Mondays at 9:00 AM UTC)

Check warning on line 297 in agent/workflows.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/workflows.mdx#L297 

Use 'cron' instead of 'Cron'.
**Context repos:** `your-org/your-product`
**Slack notifications:** `documentation` channel, `tech-writer` user

```text
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.
Expand Down
12 changes: 0 additions & 12 deletions cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Commands"
description: "Complete reference for every Mintlify CLI command and flag, including mint dev, mint build, mint validate, mint analytics, and more."

Check warning on line 3 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L3 

Use 'Dev' instead of 'dev'.
keywords: ["CLI", "mint", "commands", "flags", "reference"]
---

Expand Down Expand Up @@ -141,7 +141,7 @@
| --- | --- |
| `--page` | Filter conversations that reference a specific page in sources. |

#### `mint analytics conversation view <conversation-id>`

Check warning on line 144 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L144 

'````' should use sentence-style capitalization.

View a single conversation by ID. Use `mint analytics conversation list` to get IDs.

Expand All @@ -157,7 +157,7 @@
mint analytics conversation buckets list
```

#### `mint analytics conversation buckets view <bucket-id>`

Check warning on line 160 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L160 

'````' should use sentence-style capitalization.

View conversations in a category bucket. Use `mint analytics conversation buckets list` to get IDs.

Expand All @@ -175,7 +175,7 @@
mint config <subcommand> <key> [value]
```

| Subcommand | Description |

Check warning on line 178 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L178 

Use 'subcommands?' instead of 'Subcommand'.
| --- | --- |
| `set <key> <value>` | Set a configuration value. |
| `get <key>` | Display a configuration value. |
Expand Down Expand Up @@ -241,23 +241,11 @@
| `--local-schema` | Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production. |

<Note>
The standalone `mint openapi-check` command is deprecated. Use `mint validate` instead.

Check warning on line 244 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L244 

In general, use active voice instead of passive voice ('is deprecated').
</Note>

---

## `mint workflow`

Create a [workflow](/agent/workflows) file interactively.

```bash
mint workflow
```

The CLI prompts for a name, trigger type, and other settings, then creates a `.md` file in `.mintlify/workflows/`.

---

## `mint export`

Export your documentation as a self-contained zip archive for offline viewing and distribution.
Expand Down Expand Up @@ -375,7 +363,7 @@

## Telemetry

The CLI collects anonymous usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, and architecture. Mintlify does **not** collect personally identifiable information, project content, or file paths.

Check warning on line 366 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L366 

Did you really mean 'informat'?

By default, the CLI collects telemetry data. You can opt out at any time using the `--telemetry` flag:

Expand Down
14 changes: 0 additions & 14 deletions es/cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,20 +284,6 @@ mint validate [flags]

---

<div id="mint-workflow">
## `mint workflow`
</div>

Crea un archivo de [flujo de trabajo](/es/agent/workflows) de forma interactiva.

```bash
mint workflow
```

La CLI solicita un nombre, tipo de activador y otros ajustes, luego crea un archivo `.md` en `.mintlify/workflows/`.

---

<div id="mint-export">
## `mint export`
</div>
Expand Down
Loading
Loading