diff --git a/agent/index.mdx b/agent/index.mdx index 43d881df0..da2f91c3b 100644 --- a/agent/index.mdx +++ b/agent/index.mdx @@ -26,7 +26,7 @@ Use the agent to: - Search and revise code examples and API references across your docs. - Reference source code from any repository that has the Mintlify GitHub App installed. - Pull live context from connected apps like Slack, Notion, Linear, and Jira. -- Automate documentation maintenance with workflows. +- Automate documentation maintenance with automations. - Answer questions about your docs and technical writing topics. - Address code review feedback to maintain documentation quality. - Capture knowledge from Slack conversations and pull requests before it gets lost. @@ -62,6 +62,6 @@ Configure the agent with an `AGENTS.md` file. Get better results with focused prompts. - -Automate recurring tasks and documentation maintenance with workflows. + +Automate recurring tasks and documentation maintenance with automations. diff --git a/agent/use-cases.mdx b/agent/use-cases.mdx index 7a000369d..ab4f53c1a 100644 --- a/agent/use-cases.mdx +++ b/agent/use-cases.mdx @@ -1,7 +1,7 @@ --- title: "Use cases" description: "Explore real-world examples of using the Mintlify agent to automate documentation updates, capture knowledge, and maintain accurate docs." -keywords: ["agent workflows", "documentation workflows", "automation examples"] +keywords: ["agent automations", "documentation automations", "automation examples"] --- The agent assists with many different documentation tasks. These examples show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs. @@ -60,11 +60,11 @@ Prompt the agent with feedback from your users to make focused updates to your d For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`. -## Automate with workflows +## Automate with automations -Create workflows to automate recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product. +Create automations to automate recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product. -See [Workflows overview](/workflows/index) for more information. +See [Automations overview](/automations/index) for more information. ## Automate with the API diff --git a/ai-native.mdx b/ai-native.mdx index 03b5327db..2b8fd1e39 100644 --- a/ai-native.mdx +++ b/ai-native.mdx @@ -17,7 +17,7 @@ In addition to reading individual pages, users can chat with the [assistant](/as The [agent](/agent) helps you write and maintain documentation. It creates pull requests with proposed changes based on your prompts, pull requests, and Slack threads. Add the agent to your Slack workspace so that anyone on your team can help maintain your documentation by chatting with the agent. Or embed the agent into custom apps via the [API](/api/agent/v2/create-agent-job). -Create [workflows](/workflows/index) to run the agent on a schedule or on a push to a repository. Each workflow defines a prompt for the agent and a trigger for when to run it. +Create [automations](/automations/index) to run the agent on a schedule or on a push to a repository. Each automation defines a prompt for the agent and a trigger for when to run it. Configure popular tools like [Cursor](/guides/cursor), [Claude Code](/guides/claude-code), and [Windsurf](/guides/windsurf) to reference the Mintlify schema, your style guide, and best practices. @@ -49,7 +49,7 @@ Select any of the following cards for more information. Configure the assistant to search external sites or direct people to your support team if it can't answer their questions. - + Get documentation updates automatically on a schedule or when a push event occurs. diff --git a/assistant/index.mdx b/assistant/index.mdx index f29fbb6bd..f1726397d 100644 --- a/assistant/index.mdx +++ b/assistant/index.mdx @@ -6,7 +6,7 @@ boost: 3 --- - The assistant is on by default. All organizations receive 5,000 trial credits shared across the assistant, agent, and workflows. See [Manage billing](/assistant/configure#manage-billing) for more information about credit tiers and options. + The assistant is on by default. All organizations receive 5,000 trial credits shared across the assistant, agent, and automations. See [Manage billing](/assistant/configure#manage-billing) for more information about credit tiers and options. ## About the assistant diff --git a/automations/create.mdx b/automations/create.mdx new file mode 100644 index 000000000..6b8c5c3c0 --- /dev/null +++ b/automations/create.mdx @@ -0,0 +1,48 @@ +--- +title: "Create a custom automation" +description: "Create a custom Mintlify automation with a schedule or push trigger, context repositories, and an agent prompt to automate recurring documentation tasks." +keywords: ["automation", "automate", "cron", "agent", "custom automation"] +--- + +import GitlabAutomationSetup from '/snippets/gitlab-automation-setup.mdx'; + +## Prerequisites + +- A Mintlify project connected to a GitHub or GitLab 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) + +## 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](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. +4. Click **Create automation**. + +## 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). + + + Review the output of your custom automations to confirm they work as expected. Update your instructions to improve the results. + + + + +## Delete a custom automation + +Deleting an automation is permanent and removes its configuration and run history. + +1. Go to the [Automations](https://app.mintlify.com/products/automations) page in your dashboard. +2. Click the settings button beside an automation. +3. Click **Delete**. diff --git a/automations/index.mdx b/automations/index.mdx new file mode 100644 index 000000000..8d6340efa --- /dev/null +++ b/automations/index.mdx @@ -0,0 +1,50 @@ +--- +title: "Automations overview" +sidebarTitle: "Overview" +description: "Automate content maintenance with Mintlify automations. Run the agent on a schedule or in response to GitHub and GitLab repository pushes." +keywords: ["automation", "automate", "cron", "agent", "automations"] +boost: 5 +--- + +Automations run the agent automatically on a schedule or in response to changes in a repository. Each automation defines a prompt for the agent and a trigger for when to run it. Automations support both GitHub and GitLab repositories. + +When an automation runs, the agent reads your project content and any connected repositories, then follows the prompt to make updates. + + +Use automations that run on a schedule for recurring tasks, like publishing changelogs or auditing SEO metadata. + +Use automations that trigger on content or code changes for reactive maintenance, like translations or updating content when source code changes. + + +## Trigger types + +Automations support three trigger types. + +- **Content update**: Run when content changes push to your Mintlify project repository, including pull request merges and direct pushes. +- **Code change**: Run when a pull request merges in a connected source code repository. +- **Custom schedule**: Run on a recurring schedule. Automations queue within 10 minutes of the scheduled time. + +Each automation has exactly one trigger. You cannot combine trigger types in a single automation. + +## Usage limits + +Automation runs count toward your credit usage. See your credit usage, set overages, and manage your credit package on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. + +Each automation can run up to 500 times per day. Runs that fail do not count toward this limit. + +## Next steps + + + + Reference for all predefined automations: triggers, update modes, and required configuration. + + + Turn on predefined automations and configure triggers, update mode, and context. + + + Build an automation with your own trigger, instructions, and context repositories. + + + Choose the right trigger, write effective instructions, and review results. + + diff --git a/automations/manage.mdx b/automations/manage.mdx new file mode 100644 index 000000000..f468291b8 --- /dev/null +++ b/automations/manage.mdx @@ -0,0 +1,124 @@ +--- +title: "Manage automations" +description: "Enable, disable, trigger, and delete automations from your dashboard. Configure GitHub or GitLab triggers, schedules, context repos, and automerge." +keywords: ["cron", "push", "automerge", "context", "automation instructions", "trigger", "disable automation", "enable automation"] +--- + +import GitlabAutomationSetup from '/snippets/gitlab-automation-setup.mdx'; + +## Prerequisites + +- A Mintlify project connected to a GitHub or GitLab 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) + + + You can also create, list, and delete automations from the terminal with [`mint automation`](/cli/commands#mint-automation). The CLI is useful for scripting and CI; the dashboard is the easiest way to configure and monitor automation runs. + + +## Enable an automation + +1. Open the [Automations](https://app.mintlify.com/products/automations) page in your dashboard. +2. Click the toggle beside an automation to enable it. + + The automations dashboard. + The automations dashboard. + + + If the automation can run with default settings, it activates immediately. Otherwise, the settings panel opens so you can fill in any required configurations. + + The configuration options for an automation. + The configuration options for an automation. + +3. If the settings panel opens, fill in the required fields. +4. Click **Turn on automation**. + +To change settings for an active automation, click the settings button beside it. Use the toggle in the modal header to enable or disable the automation without leaving the settings view. + +## Configurations + +### Trigger + +Each automation has a default trigger that controls when it runs. To change the trigger, select a different option in the settings panel. + +- **Content update**: Runs whenever you push content to your project repository, including pull request merges and direct pushes. +- **Code change**: Runs when a pull request merges in a connected source code repository. You must specify at least one source repository. +- **Custom schedule**: Runs on a recurring schedule you define. Automations queue within 10 minutes of the scheduled time. + +### Update mode + +Each automation has a default mode for how it makes updates. Either directly merging changes into your content repository or opening a pull request for review. + +To require a review before the automation updates your content, select **Require review** in the settings panel. + + + For GitHub repositories, automatic updates require the Mintlify GitHub App to have bypass permissions on every ruleset targeting 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 and requires at least the Maintainer role on each project. + + +### Context repositories + +For custom automations and some predefined automations, you can add context repositories—additional source code repositories the agent reads when the automation runs. This is useful when your automation prompt references code, APIs, or other content that lives outside your project repository. + +You can add up to 10 context repositories per automation. For each GitHub repository, install the Mintlify GitHub App. Add repositories on the [GitHub App settings](https://app.mintlify.com/settings/organization/github-app) page. + +### Integrations + +For custom automations and the **Update from code changes** automation, you can enable connected [agent integrations](/agent/integrations) so the agent can pull context from tools like Slack, Notion, or Linear when the automation runs. + +To enable integrations for an automation, open its settings and select the integrations you want the agent to use in the **Available integrations** section. Only integrations already connected for your organization appear in the list. See [Agent integrations](/agent/integrations) for more information on connecting integrations. + +### Slack notifications + +Send Slack messages to one or more channels when automations run. + +To enable Slack notifications: +1. Install the [Mintlify Slack app](/agent/slack) in your workspace. +2. Click **Turn on Slack notifications** on the [Automations](https://app.mintlify.com/products/automations) page of your dashboard. + + The turn on Slack notifications button. + The turn on Slack notifications button. + +3. Select one or more notification channels. +4. Click **Save changes**. + +Once enabled, Mintlify posts to the selected channels when: + +- An automation opens a pull request for review. +- An automation pull request has been waiting for review for three days. +- An automation merges a pull request, or fails to complete. + +### Instructions + +Add optional instructions that append to the automation's base prompt on every run. Use these to adjust the style, tone, or other project-specific behaviors without changing the core automation logic. + +### Target languages + +When you enable the **Translate content** automation, select one or more languages to keep in sync with your source content. + +- Mintlify reads the [languages](/organize/navigation#languages) defined in your `docs.json` to identify your default language and preselects any already configured target languages. +- You must select at least one target language to save the automation. +- You cannot select the source language as a target. + +You can add target languages at any time by opening the automation's settings and editing the **Translate to** field. + + + +## Disable an automation + +1. Go to the [Automations](https://app.mintlify.com/products/automations) page in your dashboard. +2. Click the toggle beside an automation to disable it. + +When you re-enable a scheduled automation or change its schedule, Mintlify recalculates the next run time from the current time. Disabled automations do not retain a pending run time. + +## View run history + +Each automation keeps a log of past runs, including the status and a summary of changes made. + +1. Go to the [Automation Runs](https://app.mintlify.com/products/automations) page in your dashboard. +2. Use the dropdown menus to filter by specific automations or status. + + Automation runs page showing the automation and status filters. + Automation runs page showing the automation and status filters. + diff --git a/workflows/reference.mdx b/automations/reference.mdx similarity index 53% rename from workflows/reference.mdx rename to automations/reference.mdx index cb1ec4b58..dcdbf20d1 100644 --- a/workflows/reference.mdx +++ b/automations/reference.mdx @@ -1,24 +1,24 @@ --- -title: "Predefined workflows" -description: "Reference for all predefined Mintlify workflows, including default trigger, update mode, context repository support, and required configurations." +title: "Predefined automations" +description: "Reference for all predefined Mintlify automations, including default trigger, update mode, context repository support, and required configurations." keywords: ["predefined", "automation", "default"] --- -Mintlify includes predefined workflows for the most common documentation maintenance tasks. Each workflow has a base prompt and a default configuration. You can customize the trigger, update mode, and instructions from the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page in your dashboard. +Mintlify includes predefined automations for the most common documentation maintenance tasks. Each automation has a base prompt and a default configuration. You can customize the trigger, update mode, and instructions from the [Automations](https://app.mintlify.com/products/automations) page in your dashboard. -## Self-updating content workflows +## Self-updating content automations -Self-updating content workflows make updates based on context that you define so your content remains accurate and up to date. +Self-updating content automations make updates based on context that you define so your content remains accurate and up to date. ### Update from code changes -Monitors your source code repositories and opens pull requests to update content for changes that affect users. You can run this workflow on a schedule, which generally uses fewer credits, or on every source code pull request. By default, this workflow runs twice weekly (Tuesday and Thursday). +Monitors your source code repositories and opens pull requests to update content for changes that affect users. You can run this automation on a schedule, which generally uses fewer credits, or on every source code pull request. By default, this automation runs twice weekly (Tuesday and Thursday). -When you run the workflow on a schedule, the agent reads all merged source code pull requests since the last time the workflow ran. It groups related changes that require content updates into a pull request in your Mintlify project repository. If there are any unmerged pull requests from previous runs, the agent adds relevant changes to existing pull requests. The agent cites where the changes come from in your source code repositories. +When you run the automation on a schedule, the agent reads all merged source code pull requests since the last time the automation ran. It groups related changes that require content updates into a pull request in your Mintlify project repository. If there are any unmerged pull requests from previous runs, the agent adds relevant changes to existing pull requests. The agent cites where the changes come from in your source code repositories. -When you run the workflow on every source code pull request, the agent opens a content update pull request whenever you merge a code change that requires content updates. Use the push-based variant when you want content updates to appear as soon as code ships, rather than batched on a schedule. +When you run the automation on every source code pull request, the agent opens a content update pull request whenever you merge a code change that requires content updates. Use the push-based variant when you want content updates to appear as soon as code ships, rather than batched on a schedule. -You can enable [agent integrations](/agent/integrations) for this workflow to give the agent additional context from tools like Slack or Linear when determining what to update. +You can enable [agent integrations](/agent/integrations) for this automation to give the agent additional context from tools like Slack or Linear when determining what to update. ### Draft changelog @@ -26,21 +26,21 @@ Creates a changelog entry on a recurring schedule. Add source code repositories ### Draft improvements from assistant conversations -Reviews question trends from your [assistant](/assistant/index) to identify gaps in your content, then opens a pull request to address them. The more assistant conversations your users have, the more signal the agent has to work with. Run this workflow on a recurring schedule to keep content aligned with what users want to know about your product. +Reviews question trends from your [assistant](/assistant/index) to identify gaps in your content, then opens a pull request to address them. The more assistant conversations your users have, the more signal the agent has to work with. Run this automation on a recurring schedule to keep content aligned with what users want to know about your product. ### Draft improvements from user feedback Reviews page [feedback](/optimize/feedback)—thumbs ratings and written comments—and updates content where users have reported problems. The agent focuses on pages with recurring negative signals rather than one-off feedback, so results improve as feedback accumulates. -You must enable feedback collection on the [Add-ons](https://app.mintlify.com/products/addons) page before you can use this workflow. +You must enable feedback collection on the [Add-ons](https://app.mintlify.com/products/addons) page before you can use this automation. -## Maintenance workflows +## Maintenance automations -Maintenance workflows automate routine tasks to improve the quality and consistency of your content. You can run them on a content update trigger or on a recurring schedule. +Maintenance automations automate routine tasks to improve the quality and consistency of your content. You can run them on a content update trigger or on a recurring schedule. -Running on a content update trigger maintains your content with minimal lag. Running on a schedule is generally more credit-efficient because the agent batches work across multiple changes in a single run. The tradeoff is a delay between when content changes and when the workflow acts on it. +Running on a content update trigger maintains your content with minimal lag. Running on a schedule is generally more credit-efficient because the agent batches work across multiple changes in a single run. The tradeoff is a delay between when content changes and when the automation acts on it. -Any enabled maintenance workflows run on pull requests created by self-updating content workflows. If the maintenance workflow identifies required changes, the agent combines the work into a single pull request. For example, if you enable the **Translate content** workflow, the agent adds translations to any pull requests opened by the **Update from code changes** workflow. +Any enabled maintenance automations run on pull requests created by self-updating content automations. If the maintenance automation identifies required changes, the agent combines the work into a single pull request. For example, if you enable the **Translate content** automation, the agent adds translations to any pull requests opened by the **Update from code changes** automation. ### Translate content diff --git a/changelog.mdx b/changelog.mdx index 654387314..d72f31db2 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -31,7 +31,7 @@ noindex: true ## Bug fixes - - Long-queued or stalled workflow runs now time out reliably after 25 hours. + - Long-queued or stalled automation runs now time out reliably after 25 hours. - Renaming files between `.mdx` and other extensions in the editor now works. - Click-to-reposition the cursor in the editor file tree rename input. - Adding files to `docs.json` in the editor no longer requires a reset. @@ -39,7 +39,7 @@ noindex: true - The active page node is revealed in the editor navigation on load. - Search results anchor to the page top or title-matching section instead of arbitrary subsections. - Bad frontmatter no longer crashes page builds. - - Workflows home banner shows a toast when a custom workflow delete fails, and prefers an error message over a summary for failed runs. + - Automations home banner shows a toast when a custom automation delete fails, and prefers an error message over a summary for failed runs. - "Ran x ago" labels tick during polling. - Live badges across the product now use a consistent check icon. - Favicon proxy handles encoding headers correctly. @@ -47,12 +47,12 @@ noindex: true - Renamed contextual menu action "Open in Windsurf" to "Open in Devin Desktop" and uses the `devin://` deep link. - + - ## Agent and workflow integrations + ## Agent and automation integrations - **Agent integrations:** The agent can now connect to more third-party apps, including Google Calendar, Intercom, Jira, Linear, Notion, Salesforce, and Slack. - - **Workflow integrations:** Workflows can use the same third-party apps as context for workflow runs. + - **Automation integrations:** Automations can use the same third-party apps as context for automation runs. ## Slack agent @@ -67,7 +67,7 @@ noindex: true ## Improvements - - Workflow stale review reminders: [Workflows](/workflows) that open pull requests now send Slack reminders when reviews go stale. + - Automation stale review reminders: [Automations](/automations) that open pull requests now send Slack reminders when reviews go stale. ## Bug fixes @@ -81,7 +81,7 @@ noindex: true - Future date selection in the dashboard uses the correct styles. - + ## Editor More ways to edit and configure your docs directly from the [web editor](https://www.mintlify.com/docs/editor): @@ -101,11 +101,11 @@ noindex: true - **File attachments:** Attach files directly to the agent. - **Interrupt mid-stream:** Stop the agent while it's streaming a response if you want to redirect it. - ## Workflows + ## Automations - - **Draft improvements from user feedback:** This new workflow reviews recent [page feedback](/optimize/feedback) and opens pull requests based on what users report. - - The **update from code changes** workflow (formerly sync content with code) defaults to run on a schedule rather than triggering on every code change. When it runs, the agent scans all code changes since the last run and opens one PR per related set of documentation updates. If a PR is still open from a previous workflow run, new changes are appended to it rather than creating a new PR. This means a release worked on over several weeks produces a single docs PR to review instead of one per commit. - - Workflow titles and copy across the dashboard have been refreshed for clarity. + - **Draft improvements from user feedback:** This new automation reviews recent [page feedback](/optimize/feedback) and opens pull requests based on what users report. + - The **update from code changes** automation (formerly sync content with code) defaults to run on a schedule rather than triggering on every code change. When it runs, the agent scans all code changes since the last run and opens one PR per related set of documentation updates. If a PR is still open from a previous automation run, new changes are appended to it rather than creating a new PR. This means a release worked on over several weeks produces a single docs PR to review instead of one per commit. + - Automation titles and copy across the dashboard have been refreshed for clarity. ## API playground @@ -116,8 +116,8 @@ noindex: true Agents that connect to the admin MCP can now read and modify most dashboard settings directly. This lets you configure your entire Mintlify setup without touching the dashboard and gives AI agents direct access to your analytics data. Supported operations include: - - Enabling and disabling workflows - - Creating custom workflows + - Enabling and disabling automations + - Creating custom automations - Managing authentication settings - Configuring custom domains - Reading and analyzing analytics data @@ -147,7 +147,7 @@ noindex: true - Slash commands and the file settings sheet behave correctly in the file tree. - + ## Web Editor We've continued to enhance our web editor with a number of functionality and UI improvements. @@ -158,11 +158,11 @@ noindex: true - **File-tree navigation by default:** Newly onboarded users start in the file-tree view instead of the legacy list view. - **Browser tab titling:** The browser tab name now dynamically updates to match the active file, so you always know which file you're editing. - ## Workflows + ## Automations - - New **Draft improvements from assistant conversations** workflow reviews trends from user questions and suggests documentation updates to address gaps. See [Workflows](/workflows/reference#draft-improvements-from-assistant-conversations). - - **Context repositories** can now be configured directly for some workflows so you can add the repos a workflow should reference while running. - - Workflow settings now open in a **side panel** instead of a modal, making it easier to tweak settings while reviewing Workflow Runs. + - New **Draft improvements from assistant conversations** automation reviews trends from user questions and suggests documentation updates to address gaps. See [Automations](/automations/reference#draft-improvements-from-assistant-conversations). + - **Context repositories** can now be configured directly for some automations so you can add the repos an automation should reference while running. + - Automation settings now open in a **side panel** instead of a modal, making it easier to tweak settings while reviewing Automation Runs. ## Search Improvements @@ -171,7 +171,7 @@ noindex: true ## Improvements - - **Slack Agent**: The [Slack agent](https://www.mintlify.com/docs/agent/slack) now supports **GitLab** alongside GitHub for repository-aware workflows. + - **Slack Agent**: The [Slack agent](https://www.mintlify.com/docs/agent/slack) now supports **GitLab** alongside GitHub for repository-aware automations. - **Sidebar Navigation:** Sidebar navigation state and scroll position are now preserved across page navigation. - **Accessibility:** Accessibility improvements across docs, including the table of contents and mobile agent panel. - **AsyncAPI schemas**: Array and combinatorial (`oneOf` / `anyOf` / `allOf`) schemas now expand to show their child attributes in the API reference. @@ -189,7 +189,7 @@ noindex: true ## Improvements - - **Workflows**: New **Add GitHub repositories** link in the Workflows repository dropdown makes it easier to connect additional repositories without leaving the page. The Workflow Runs tab now defaults to **All runs** when nothing currently needs review, and a **View all runs** button on the empty state clears active filters in one click. + - **Automations**: New **Add GitHub repositories** link in the Automations repository dropdown makes it easier to connect additional repositories without leaving the page. The Automation Runs tab now defaults to **All runs** when nothing currently needs review, and a **View all runs** button on the empty state clears active filters in one click. - **Mintlify Agent**: The [Mintlify agent](https://www.mintlify.com/docs/agent/slack) can now be installed in your Slack workspace even without having a Mintlify-hosted deployment. Additionally, viewer-role users can now ask questions and get answers using read-only tools, and the agent now uses prior thread images and message reactions as additional context. - **Schema graph callbacks**: API reference pages now render OpenAPI `callbacks` in the schema graph. - **Danish language support** added. @@ -232,16 +232,16 @@ noindex: true - The [feedback dashboard](/optimize/feedback) detailed feedback view now only shows submissions that include written comments, making qualitative feedback easier to scan. - - ## Workflows + + ## Automations - Workflows have been rebuilt with a new [dashboard experience](https://app.mintlify.com/products/workflows?tab=workflows). + Automations have been rebuilt with a new [dashboard experience](https://app.mintlify.com/products/automations). - - **Optimized workflow templates**: Mintlify maintains prompts for common content creation and maintenance tasks. Turn on these workflows and let the agent handle the rest. Mintlify routinely improves the prompts so that you don't have to. - - **Quicker setup**: Toggle on a workflow and adjust any optional settings. No more YAML configuration or iterating on Markdown prompts. - - **Custom workflows**: In addition to built-in workflows, you can create your own workflows. + - **Optimized automation templates**: Mintlify maintains prompts for common content creation and maintenance tasks. Turn on these automations and let the agent handle the rest. Mintlify routinely improves the prompts so that you don't have to. + - **Quicker setup**: Toggle on an automation and adjust any optional settings. No more YAML configuration or iterating on Markdown prompts. + - **Custom automations**: In addition to built-in automations, you can create your own automations. - See the [workflows](/workflows) documentation for more details. + See the [automations](/automations) documentation for more details. ## Editor @@ -293,7 +293,7 @@ noindex: true - Fixed media file paths with special characters not loading correctly. - Fixed search results not finding bare queries like `search`. - Fixed self-serve deployment errors in the dashboard. - - Fixed a workflow card toggle that could blank the dashboard page. + - Fixed an automation card toggle that could blank the dashboard page. @@ -355,9 +355,9 @@ noindex: true A new step-by-step wizard on the Git settings page guides you through connecting a GitHub or GitLab repository for the first time. Choose between one-click cloning or manual repository selection, with support for organization selection, branch configuration, and subdirectory setup. - ## GitLab OAuth for workflows + ## GitLab OAuth for automations - [Workflows](/workflows) now support GitLab repositories through OAuth authentication. Connect your GitLab account from the dashboard to use GitLab repos as documentation sources, trigger repositories, or context repositories in your workflows. The agent opens merge requests on GitLab just like it opens pull requests on GitHub. + [Automations](/automations) now support GitLab repositories through OAuth authentication. Connect your GitLab account from the dashboard to use GitLab repos as documentation sources, trigger repositories, or context repositories in your automations. The agent opens merge requests on GitLab just like it opens pull requests on GitHub. ## Improvements @@ -370,7 +370,7 @@ noindex: true ## Deprecations - - File-based workflows are deprecated. Create workflows from the dashboard instead. Existing workflows from files continue to work, but new workflows must be created in the dashboard. + - File-based automations are deprecated. Create automations from the dashboard instead. Existing automations from files continue to work, but new automations must be created in the dashboard. ## Bug fixes @@ -423,7 +423,7 @@ noindex: true - CLI UX improvements: grayed-out login URLs for clarity, standardized log formatting, and `mint status` now shows the CLI version. - OpenAPI `x-group` extension support for organizing API endpoints into custom groups. - Horizontal rules (`
`) are now supported in MDX content. - - [Workflows](/workflows) now surface in the dashboard inbox for easier tracking. The workflow list also displays PR names for quicker identification. + - [Automations](/automations) now surface in the dashboard inbox for easier tracking. The automation list also displays PR names for quicker identification. - The `mint export` command now includes API reference pages generated from OpenAPI specifications. - The slash command menu in the editor has been redesigned with improved organization and discoverability. - Improved the UI of the editor publish flow and page creation interface. @@ -433,7 +433,7 @@ noindex: true ## Bug fixes - Fixed custom heading IDs not being processed before MDX parsing, which could cause anchors to break on certain pages. - - Fixed the SEO and metadata audit workflow template from incorrectly modifying API endpoint pages. + - Fixed the SEO and metadata audit automation template from incorrectly modifying API endpoint pages. - Fixed deprecated label text wrapping in the dashboard. - Fixed inline formatting (bold, italic, code) not applying correctly in the editor in certain contexts. - Fixed directory folder icon colors not matching the configured theme. @@ -461,7 +461,7 @@ noindex: true - Redesigned the editor configuration settings page with an improved layout and autosave support. - Pages auto-generated from OpenAPI specifications now appear in the web editor as read-only entries. - Video support in [live preview](/editor/live-preview). Embedded mp4, webm, and mov files now render correctly during local development. - - [Workflows](/workflows) can now be disabled and re-enabled from the dashboard. + - [Automations](/automations) can now be disabled and re-enabled from the dashboard. - Assistant analytics now show usage broken down by source (web vs API) in the dashboard. - Authenticated MCP search now correctly filters results based on the user's authentication groups. - Slack agent responses now show tool call summaries instead of raw tool calls for clearer information of what the agent is doing. @@ -475,7 +475,7 @@ noindex: true - Fixed layout shift caused by the text selection tooltip. - Fixed badge and icon visual diff detection in the editor. - Fixed OpenAPI title and description not resolving for pages referenced by file path. - - Fixed [workflow](/workflows) automerge toggle not properly disabling when set to off. + - Fixed [automation](/automations) automerge toggle not properly disabling when set to off. - Fixed API playground including optional object fields with required children in generated request bodies. - Fixed keyboard activation for the feedback analytics table selection checkbox. @@ -517,7 +517,7 @@ noindex: true - [Custom heading IDs](/create/text#custom-heading-ids) now supported. Search results deep-link to sections that use custom IDs. - Navigation entries in `docs.json` now support anchor links (`#` links). - - Workflows dashboard redesigned with card view, clearer run history, action dropdowns, and improved empty states. + - Automations dashboard redesigned with card view, clearer run history, action dropdowns, and improved empty states. - Editor navigation now syncs with the server for persistent changes and multi-user conflict resolution. - MCP search now respects authentication permissions, so search results only include pages the user has access to. - [Heap analytics](/integrations/analytics/heap) now properly forwards page views and custom events. @@ -560,9 +560,9 @@ noindex: true ## Improvements - User profile pictures now displayed throughout the dashboard for a more personalized experience. - - Workflow templates updated with improved prompts. - - Workflow run history now viewable from the dashboard with the ability to monitor status and close PRs. - - Slack notifications for workflows now configurable from the dashboard. + - Automation templates updated with improved prompts. + - Automation run history now viewable from the dashboard with the ability to monitor status and close PRs. + - Slack notifications for automations now configurable from the dashboard. - Editor performance improvements: fixed typing latency and persistence blocking in large repositories, virtualized file lists for repositories with many files. - Card layout shift on initial page load eliminated. - Dashboard analytics date-picker responsiveness improved. @@ -584,14 +584,14 @@ noindex: true - Fixed hidden page children not appearing in decorated navigation. - - ## Workflow templates + + ## Automation templates - Create [workflows](/workflows) faster with pre-built templates in the [dashboard](https://app.mintlify.com/products/workflows). Choose from templates for changelog generation, API docs sync, feature documentation drafts, broken link detection, SEO audits, and more. Templates include optimized prompts and trigger configurations to get you started quickly. + Create [automations](/automations) faster with pre-built templates in the [dashboard](https://app.mintlify.com/products/automations). Choose from templates for changelog generation, API docs sync, feature documentation drafts, broken link detection, SEO audits, and more. Templates include optimized prompts and trigger configurations to get you started quickly. - ## Workflow CLI command + ## Automation CLI command - Create [workflows](/workflows) files from the command line with the `mint workflow` CLI command. Interactive prompts guide you through name, trigger, context, and instructions. + Create [automations](/automations) files from the command line with the `mint automation` CLI command. Interactive prompts guide you through name, trigger, context, and instructions. ## Agent API v2 @@ -610,7 +610,7 @@ noindex: true - YouTube and Loom embeds available in the editor slash command menu - Localized footer and navbar content per locale - Slack assistant shows status indicators while processing - - Workflows can now send Slack notifications with auto-merge status + - Automations can now send Slack notifications with auto-merge status - Editor now supports spellcheck - Dashboard layout improvements for mobile and responsive views @@ -623,8 +623,8 @@ noindex: true - Fixed PDF export styling issues - Fixed footer hidden on custom pages for Mint, Maple, Willow, and Linden themes - Fixed `.md` routes not generating titles from slugs - - Fixed cron workflows created via the dashboard not auto-triggering - - Fixed recursive workflow runs + - Fixed cron automations created via the dashboard not auto-triggering + - Fixed recursive automation runs - Fixed agent from re-creating a PR when prompted for follow up changes - Fixed agent session errors for multi-lingual sessions @@ -648,7 +648,7 @@ noindex: true ## Improvements - - Workflows now support up to 50 runs per day, increased from 20. + - Automations now support up to 50 runs per day, increased from 20. - [Full base URL](/organize/settings-api) now supported in the API playground by configuring `api.url` in `docs.json`. - Dashboard layout updated with improved navigation and sidebar access for the editor and settings pages. - Editor search bar redesigned with better UX for finding and navigating to files. @@ -666,12 +666,12 @@ noindex: true - Fixed mobile zoom behavior for input fields. - - ## Workflows + + ## Automations - Automate documentation tasks with [workflows](/workflows). Set up scheduled or event-triggered automations that run the agent to update your documentation. + Automate documentation tasks with [automations](/automations). Set up scheduled or event-triggered automations that run the agent to update your documentation. - Workflows are in beta and available on all plans. + Automations are in beta and available on all plans. ## Comments and suggestions diff --git a/cli/commands.mdx b/cli/commands.mdx index 752f351ff..ca1c976d6 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -69,7 +69,7 @@ mint status ## `mint workflow` -Create, list, and delete [workflows](/workflows) from the terminal. Requires authentication with `mint login`. +Create, list, and delete [workflows](/automations) from the terminal. Requires authentication with `mint login`. ```bash mint workflow [flags] diff --git a/credits.mdx b/credits.mdx index 268e7fbf1..8a3bbc4fd 100644 --- a/credits.mdx +++ b/credits.mdx @@ -1,6 +1,6 @@ --- title: "Credit pricing" -description: "Understand how Mintlify credits work for assistant messages, agent runs, and workflows, including how we bill credit tiers, overages, and rollovers." +description: "Understand how Mintlify credits work for assistant messages, agent runs, and automations, including how we bill credit tiers, overages, and rollovers." keywords: ["credits", "billing", "pricing", "AI chat", "messages", "tiers", "usage"] --- @@ -8,7 +8,7 @@ Some Mintlify features consume credits. * Assistant responses * Agent runs in the editor or on Slack -* Workflow runs +* Automation runs For the most current pricing information, see the [Pricing page](https://mintlify.com/pricing) or view the [Usage](https://app.mintlify.com/settings/organization/usage) page in your dashboard. @@ -49,9 +49,9 @@ Different features consume different amounts of credits per interaction: | Editor agent run | 115 | | Slack agent run | 110 | -Workflows also consume credits when they run: +Automations also consume credits when they run: -| Workflow | Average credits per run | +| Automation | Average credits per run | |:---------|:------------------------| | Update from code changes | 180 | | Update from assistant conversations | 212 | @@ -66,12 +66,12 @@ Workflows also consume credits when they run: Use the averages in the [How credits work](#how-credits-work) section to estimate your monthly credit needs. -For example, if your docs site handles 500 assistant responses per month, that's roughly 11,500 credits (500 × 23). Adding a weekly broken link detection workflow adds about 1,140 credits per month (4 × 285). +For example, if your docs site handles 500 assistant responses per month, that's roughly 11,500 credits (500 × 23). Adding a weekly broken link detection automation adds about 1,140 credits per month (4 × 285). After using credit-powered features for a month, review your usage patterns to see if you should adjust your tier. ## Cost optimization -**Schedule workflows instead of triggering on every push.** Workflows like SEO audits, writing style checks, and broken link detection don't need to run on every code change. Running these on a daily or weekly cron schedule rather than on every push significantly reduces credit consumption without meaningful impact on content quality. +**Schedule automations instead of triggering on every push.** Automations like SEO audits, writing style checks, and broken link detection don't need to run on every code change. Running these on a daily or weekly cron schedule rather than on every push significantly reduces credit consumption without meaningful impact on content quality. -**Monitor your usage patterns.** The [Usage](https://app.mintlify.com/settings/organization/usage) page in your dashboard shows a breakdown by feature category. If a particular workflow is consuming more credits than expected, review its trigger or any custom instructions. +**Monitor your usage patterns.** The [Usage](https://app.mintlify.com/settings/organization/usage) page in your dashboard shows a breakdown by feature category. If a particular automation is consuming more credits than expected, review its trigger or any custom instructions. diff --git a/dashboard/audit-logs.mdx b/dashboard/audit-logs.mdx index 4873d5ac8..16ababa3d 100644 --- a/dashboard/audit-logs.mdx +++ b/dashboard/audit-logs.mdx @@ -51,7 +51,7 @@ Filter audit logs to find specific activities. | Billing | Subscription updates, add-on purchases, and invoice views. | | Quota | Overage policy and alert configuration changes. | | User | Individual user notification settings. | -| Workflows | Workflow configurations and repository management. | +| Automations | Automation configurations and repository management. | | Audit log | Audit log views and exports. | | Auth | Login attempts, logouts, and session creations. | diff --git a/deploy/gitlab-self-hosted.mdx b/deploy/gitlab-self-hosted.mdx index 0d1f7a9e7..5838ebc98 100644 --- a/deploy/gitlab-self-hosted.mdx +++ b/deploy/gitlab-self-hosted.mdx @@ -1,17 +1,17 @@ --- title: "Self-hosted GitLab OAuth" -description: "Connect a self-hosted GitLab instance to Mintlify via OAuth so workflows can clone repositories, push commits, and open merge requests on your behalf." -keywords: ["GitLab", "self-hosted", "OAuth", "workflows", "enterprise"] +description: "Connect a self-hosted GitLab instance to Mintlify via OAuth so automations can clone repositories, push commits, and open merge requests on your behalf." +keywords: ["GitLab", "self-hosted", "OAuth", "automations", "enterprise"] --- -Mintlify supports OAuth-based authorization for self-hosted GitLab instances, in addition to gitlab.com. OAuth lets the Mintlify agent act as a GitLab user during workflow runs: cloning repositories, pushing commits, opening merge requests, and registering project webhooks. +Mintlify supports OAuth-based authorization for self-hosted GitLab instances, in addition to gitlab.com. OAuth lets the Mintlify agent act as a GitLab user during automation runs: cloning repositories, pushing commits, opening merge requests, and registering project webhooks. -You must configure OAuth authorization for self-hosted GitLab instances to support [workflows](/workflows). +You must configure OAuth authorization for self-hosted GitLab instances to support [automations](/automations). Unlike gitlab.com, where Mintlify ships a single OAuth application that every customer authorizes against, each self-hosted instance must register its own OAuth application. Create the application on your GitLab instance, share its credentials with Mintlify, and then go through an OAuth authorization to connect a user. - This guide is only for the **OAuth** integration that powers workflows. You must configure the deployment-side connection (used for content sync and previews) separately with a deploy token, see the [GitLab guide](/deploy/gitlab). The OAuth integration depends on the deployment-side connection. + This guide is only for the **OAuth** integration that powers automations. You must configure the deployment-side connection (used for content sync and previews) separately with a deploy token, see the [GitLab guide](/deploy/gitlab). The OAuth integration depends on the deployment-side connection. ## Prerequisites @@ -62,10 +62,10 @@ Unlike gitlab.com, where Mintlify ships a single OAuth application that every cu Expand the connection in the dashboard. Mintlify lists every group your authorizing user has Maintainer or higher access to, plus a **Personal projects** entry for projects in the user's personal namespace. - Check the box next to each project that should participate in workflows. Mintlify registers a webhook on the project, generates a secret token, and stores it encrypted. From then on, Mintlify receives push and merge-request events from your instance for that project. + Check the box next to each project that should participate in automations. Mintlify registers a webhook on the project, generates a secret token, and stores it encrypted. From then on, Mintlify receives push and merge-request events from your instance for that project. - The connecting user must have **Maintainer** role on a project for Mintlify to mint short-lived project access tokens during workflow runs. Without Maintainer, the agent can read but cannot push commits or open merge requests. + The connecting user must have **Maintainer** role on a project for Mintlify to mint short-lived project access tokens during automation runs. Without Maintainer, the agent can read but cannot push commits or open merge requests. diff --git a/docs.json b/docs.json index 2e062e046..3e544cc4f 100644 --- a/docs.json +++ b/docs.json @@ -113,12 +113,12 @@ }, "ai/mintlify-mcp", { - "group": "Workflows", + "group": "Automations", "pages": [ - "workflows/index", - "workflows/reference", - "workflows/manage", - "workflows/create" + "automations/index", + "automations/reference", + "automations/manage", + "automations/create" ] }, { @@ -308,7 +308,7 @@ "pages": [ "guides/assistant-embed", "guides/configure-automerge", - "guides/use-workflows", + "guides/use-automations", "guides/claude-code", "guides/cursor", "guides/geo", diff --git a/guides/configure-automerge.mdx b/guides/configure-automerge.mdx index 06faae779..5c947e2d1 100644 --- a/guides/configure-automerge.mdx +++ b/guides/configure-automerge.mdx @@ -5,10 +5,10 @@ description: "Set up GitHub workflows to automatically merge Mintlify pull reque keywords: ["automerge", "ruleset", "branch protection", "bypass"] --- -Add the Mintlify GitHub App to a ruleset's bypass list so that the app can create and merge pull requests without review and status check requirements blocking it. This lets you configure [workflows](/workflows/index) to automatically merge changes to `main`. +Add the Mintlify GitHub App to a ruleset's bypass list so that the app can create and merge pull requests without review and status check requirements blocking it. This lets you configure [automations](/automations/index) to automatically merge changes to `main`. - The Mintlify GitHub App must have bypass permissions on **every** ruleset that targets your deploy branch, including rulesets defined at the organization level and the repository level. If any ruleset is missing the bypass entry, the workflow creates a PR, but does not merge it. + The Mintlify GitHub App must have bypass permissions on **every** ruleset that targets your deploy branch, including rulesets defined at the organization level and the repository level. If any ruleset is missing the bypass entry, the automation creates a PR, but does not merge it. ## Prerequisites @@ -45,4 +45,4 @@ Repeat these steps for every ruleset that applies to your deploy branch. Both ** ## Verify the setup 1. **For contributors**: Open a PR targeting `main`. Confirm that it still requires approval and passing status checks before you can merge. -2. **For workflows**: Trigger a workflow with automerge enabled. Confirm that the workflow runs and successfully merges a PR. +2. **For automations**: Trigger an automation with automerge enabled. Confirm that the automation runs and successfully merges a PR. diff --git a/guides/improving-docs.mdx b/guides/improving-docs.mdx index dcbaac8f9..6865623dd 100644 --- a/guides/improving-docs.mdx +++ b/guides/improving-docs.mdx @@ -95,7 +95,7 @@ Measuring is only useful if it drives action. A few frameworks for deciding what - **Focus on key user journeys.** Identify the three to five tasks that are most critical for your product's success and ensure the documentation supporting those tasks is excellent before worrying about the rest. - Use [workflows](/workflows) to automate recurring improvements—like opening a pull request with suggested fixes for pages flagged by low feedback scores. + Use [automations](/automations) to automate recurring improvements—like opening a pull request with suggested fixes for pages flagged by low feedback scores. ## Frequently asked questions diff --git a/guides/index.mdx b/guides/index.mdx index 4602db30d..cdf210576 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -15,8 +15,8 @@ Above all else, consider your users' needs and goals. Document what helps them u Use AI-powered tools to accelerate your documentation workflow. - [Build an in-app assistant](/guides/assistant-embed): Tutorial that teaches how to add an AI chat bot in a React app to help users find answers from your documentation. -- [Configure automerge](/guides/configure-automerge): Add the Mintlify GitHub App to a ruleset bypass list to enable automatic merging for workflows. -- [Use workflows](/guides/use-workflows): Choose the right workflow trigger, write effective instructions, and get consistent results from automated content maintenance. +- [Configure automerge](/guides/configure-automerge): Add the Mintlify GitHub App to a ruleset bypass list to enable automatic merging for automations. +- [Use automations](/guides/use-automations): Choose the right automation trigger, write effective instructions, and get consistent results from automated content maintenance. - [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Guides for using AI coding assistants to maintain documentation. - [GEO](/guides/geo): Best practices for optimizing your documentation for AI search and answer engines. diff --git a/guides/internationalization.mdx b/guides/internationalization.mdx index 86fbf0957..1e2f48552 100644 --- a/guides/internationalization.mdx +++ b/guides/internationalization.mdx @@ -304,7 +304,7 @@ Keep translations accurate and synchronized with your source content. ### Automated translations -For automated translation solutions, [set up a workflow](/workflows) to run the agent on a schedule or in response to repository pushes. +For automated translation solutions, [set up an automation](/automations) to run the agent on a schedule or in response to repository pushes. ### External translation providers diff --git a/guides/maintenance.mdx b/guides/maintenance.mdx index 44659b330..4497cec07 100644 --- a/guides/maintenance.mdx +++ b/guides/maintenance.mdx @@ -52,7 +52,7 @@ Manually tracking review dates across hundreds of pages doesn't scale. Automate - Use [CI checks](/deploy/ci) to enforce frontmatter requirements and catch broken links on every pull request - Use [workflows](/workflows) to run automated maintenance checks on a schedule—flagging stale content, checking for missing metadata, or surfacing pages with consistent low feedback scores. + Use [automations](/automations) to run automated maintenance checks on a schedule—flagging stale content, checking for missing metadata, or surfacing pages with consistent low feedback scores. ## Automate what you can diff --git a/guides/navigation.mdx b/guides/navigation.mdx index fa22ccd15..397c9c583 100644 --- a/guides/navigation.mdx +++ b/guides/navigation.mdx @@ -117,7 +117,7 @@ A practical cadence: - **Revisit top-level structure annually.** As docs grow, what worked at 20 pages may not work at 200. - Use [workflows](/workflows) to automate recurring checks like surfacing pages with low feedback scores or flagging navigation items that rarely get clicks. + Use [automations](/automations) to automate recurring checks like surfacing pages with low feedback scores or flagging navigation items that rarely get clicks. To configure navigation in Mintlify—tabs, groups, anchors, and page ordering—see the [navigation reference](/organize/navigation). diff --git a/guides/seo.mdx b/guides/seo.mdx index 99cfc5bc9..03a009aa6 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -127,7 +127,7 @@ A practical approach: - Check for broken links with `mint broken-links` before publishing - Use [workflows](/workflows) to automate SEO maintenance tasks. + Use [automations](/automations) to automate SEO maintenance tasks. Stale documentation creates a second problem beyond SEO: if users find your page through search but the information is wrong, they lose trust in your docs. diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index 9b96e3034..ef26c8580 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -121,7 +121,7 @@ Writing principles only stick if they're part of a repeatable workflow. A few wa - **Existing style guides:** Rather than writing rules from scratch, start from an established guide. The [Google Developer Documentation Style Guide](https://developers.google.com/style), [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/), and [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse) are all free and widely used. - Use a [workflow](/workflows) to run a style audit on a schedule or whenever changes push to your docs repository. + Use a [automation](/automations) to run a style audit on a schedule or whenever changes push to your docs repository. ## Frequently asked questions diff --git a/guides/use-workflows.mdx b/guides/use-automations.mdx similarity index 53% rename from guides/use-workflows.mdx rename to guides/use-automations.mdx index fe9ea424d..303af9ef6 100644 --- a/guides/use-workflows.mdx +++ b/guides/use-automations.mdx @@ -1,14 +1,14 @@ --- -title: "Use workflows" -description: "Use Mintlify workflows to automate recurring docs maintenance: choose the right trigger, write effective instructions, and get consistent agent results." -keywords: ["workflows", "automation", "automate", "workflow guide", "workflow instructions", "agent automation", "self updating"] +title: "Use automations" +description: "Use Mintlify automations to automate recurring docs maintenance: choose the right trigger, write effective instructions, and get consistent agent results." +keywords: ["automations", "automation", "automate", "automation guide", "automation instructions", "agent automation", "self updating"] --- -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. +Automations run the agent automatically so your content stays accurate without manual effort. This guide covers how to choose the right automation, configure it effectively, and write instructions that produce consistent results. -## When to use workflows +## When to use automations -Workflows are best for tasks that are: +Automations 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. @@ -18,7 +18,7 @@ For one-off or exploratory tasks, use the agent directly in the [dashboard](http ## Choose a trigger -Each workflow runs on one of three trigger types. Choose the one that matches when you need the work done. +Each automation runs on one of three trigger types. Choose the one that matches when you need the work done. | Trigger | Use when | |---|---| @@ -26,21 +26,21 @@ Each workflow runs on one of three trigger types. Choose the one that matches wh | Code change | The task should run when source code changes—updating API specifications or documentation after a PR merges. | | Custom schedule | The task should run on a fixed cadence regardless—publishing weekly changelogs or running periodic grammar checks. | -## Predefined workflows +## Predefined automations -Mintlify includes predefined workflows for the most common content maintenance tasks. Toggle any of them on from the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page of your dashboard. +Mintlify includes predefined automations for the most common content maintenance tasks. Toggle any of them on from the [Automations](https://app.mintlify.com/products/automations) page of your dashboard. -See [Predefined workflows](/workflows/reference) for more details. +See [Predefined automations](/automations/reference) for more details. -## Custom workflows +## Custom automations -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. +Create a custom automation for tasks that aren't covered by the predefined options. Custom automations give you full control over the trigger, instructions, and context repositories. -See [Create a custom workflow](/workflows/create) for setup steps. +See [Create a custom automation](/automations/create) 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. +Custom automation 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. @@ -64,7 +64,7 @@ Review every page in the /api-reference directory. For each endpoint, confirm th 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. +**Keep scope narrow.** An automation that does one thing well is more reliable than one that tries to do many things. Split complex tasks across multiple automations. **Specify files and directories.** The more precise you are about where the agent should look, the less time it spends searching. @@ -75,14 +75,14 @@ For each broken link, either fix the path or remove the link if no replacement e ### Use context repositories -For custom workflows and some predefined workflows, you can add context repositories the agent reads when the workflow runs. +For custom automations and some predefined automations, you can add context repositories the agent reads when the automation 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. +- The automation prompt refers to files outside your Mintlify project repository. -You can add up to 10 context repositories per workflow. +You can add up to 10 context repositories per automation. ### Update mode @@ -93,16 +93,16 @@ Decide how much review you want before changes go live. ## 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. +Every automation run consumes credits. For example, most **update from code changes** automation 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. +Scheduling cron jobs to run at specific times gives you more precise control over credit usage. For example, run an automation once a day or once a week to know exactly how many pull requests it creates per month. Push-triggered automations can vary more from month to month because they depend on how often content or code changes. -## Review and improve workflow results +## Review and improve automation results -Workflows run automatically, but they benefit from periodic review. +Automations run automatically, but they benefit from periodic review. -1. Open the **Runs** tab on the [Workflows](https://app.mintlify.com/products/workflows) page to see recent run history and status. +1. Open the **Runs** tab on the [Automations](https://app.mintlify.com/products/automations) 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. +3. If results are inconsistent, refine your instructions: add more specific procedures, narrow the file scope, or split the automation into smaller tasks. -A few review cycles after enabling a new workflow are usually enough to dial in the instructions. +A few review cycles after enabling a new automation are usually enough to dial in the instructions. diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 22c07d018..49405f3cc 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -785,7 +785,7 @@ We currently support the following languages for localization: } ``` -For automated translations, [set up a workflow](/workflows) to run the agent on a schedule or in response to repository pushes. +For automated translations, [set up an automation](/automations) to run the agent on a schedule or in response to repository pushes. ## Nesting diff --git a/redirects.json b/redirects.json index bb429f8e3..04f770820 100644 --- a/redirects.json +++ b/redirects.json @@ -389,7 +389,7 @@ }, { "source": "/ai/autopilot", - "destination": "/workflows/index" + "destination": "/automations/index" }, { "source": "/ai/slack-app", @@ -405,7 +405,7 @@ }, { "source": "/ai/suggestions", - "destination": "/workflows/index" + "destination": "/automations/index" }, { "source": "/insights/overview", @@ -421,15 +421,15 @@ }, { "source": "/agent/suggestions", - "destination": "/workflows/index" + "destination": "/automations/index" }, { "source": "/agent/workflows", - "destination": "/workflows/index" + "destination": "/automations/index" }, { "source": "/agent/workflows/:page", - "destination": "/workflows/:page" + "destination": "/automations/:page" }, { "source": "/agent/quickstart", @@ -453,6 +453,26 @@ }, { "source": "/workflows/enable", - "destination": "/workflows/manage" + "destination": "/automations/manage" + }, + { + "source": "/workflows/index", + "destination": "/automations/index" + }, + { + "source": "/workflows/reference", + "destination": "/automations/reference" + }, + { + "source": "/workflows/manage", + "destination": "/automations/manage" + }, + { + "source": "/workflows/create", + "destination": "/automations/create" + }, + { + "source": "/guides/use-workflows", + "destination": "/guides/use-automations" } ] diff --git a/what-is-mintlify.mdx b/what-is-mintlify.mdx index d07a265a1..3d8f34725 100644 --- a/what-is-mintlify.mdx +++ b/what-is-mintlify.mdx @@ -37,7 +37,7 @@ Built-in AI features help people and AI find and understand your content, and he The **assistant** lets your users ask questions and get cited answers from your content. -The **agent** helps your team create and maintain content by generating updates from scheduled workflows, pull requests merging in your feature repository, or Slack threads. +The **agent** helps your team create and maintain content by generating updates from scheduled automations, pull requests merging in your feature repository, or Slack threads. See [AI-native documentation](/ai-native) for an overview of all AI features. diff --git a/workflows/create.mdx b/workflows/create.mdx deleted file mode 100644 index d75426957..000000000 --- a/workflows/create.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Create a custom workflow" -description: "Create a custom Mintlify workflow with a schedule or push trigger, context repositories, and an agent prompt to automate recurring documentation tasks." -keywords: ["automation", "automate", "cron", "agent", "custom workflow"] ---- - -import GitlabWorkflowSetup from '/snippets/gitlab-workflow-setup.mdx'; - -## Prerequisites - -- A Mintlify project connected to a GitHub or GitLab repository -- For GitHub: the [Mintlify GitHub App](/deploy/github) installed on every repository you plan to use in the workflow -- For GitLab: a connected GitLab account (see [GitLab setup](#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](https://app.mintlify.com/products/workflows?tab=workflows) page in your dashboard. -2. Click **Create a custom workflow**. -3. Configure the workflow name, trigger, instructions, context repositories, integrations, 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 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 workflows rather than combining them into one prompt. - -For more examples and patterns, see [Use workflows](/guides/use-workflows). - - - Review the output of your custom workflows to confirm they work as expected. Update your instructions to improve the results. - - - - -## Delete a custom workflow - -Deleting a workflow is permanent and removes its configuration and run history. - -1. Go to the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page in your dashboard. -2. Click the settings button beside a workflow. -3. Click **Delete**. diff --git a/workflows/index.mdx b/workflows/index.mdx deleted file mode 100644 index 1f730832c..000000000 --- a/workflows/index.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Workflows overview" -sidebarTitle: "Overview" -description: "Automate content maintenance with Mintlify workflows. Run the agent on a schedule or in response to GitHub and GitLab repository pushes." -keywords: ["automation", "automate", "cron", "agent", "workflows"] -boost: 5 ---- - -Workflows run the agent automatically on a schedule or in response to changes in a repository. Each workflow defines a prompt for the agent and a trigger for when to run it. Workflows support both GitHub and GitLab repositories. - -When a workflow runs, the agent reads your project content and any connected repositories, then follows the prompt to make updates. - - -Use workflows that run on a schedule for recurring tasks, like publishing changelogs or auditing SEO metadata. - -Use workflows that trigger on content or code changes for reactive maintenance, like translations or updating content when source code changes. - - -## Trigger types - -Workflows support three trigger types. - -- **Content update**: Run when content changes push to your Mintlify project repository, including pull request merges and direct pushes. -- **Code change**: Run when a pull request merges in a connected source code repository. -- **Custom schedule**: Run on a recurring schedule. Workflows queue within 10 minutes of the scheduled time. - -Each workflow has exactly one trigger. You cannot combine trigger types in a single workflow. - -## Usage limits - -Workflow runs count toward your credit usage. See your credit usage, set overages, and manage your credit package on the [Usage](https://app.mintlify.com/settings/organization/usage) page of your dashboard. - -Each workflow can run up to 500 times per day. Runs that fail do not count toward this limit. - -## Next steps - - - - Reference for all predefined workflows: triggers, update modes, and required configuration. - - - Turn on predefined workflows and configure triggers, update mode, and context. - - - Build a workflow with your own trigger, instructions, and context repositories. - - - Choose the right trigger, write effective instructions, and review results. - - diff --git a/workflows/manage.mdx b/workflows/manage.mdx deleted file mode 100644 index 6d893e623..000000000 --- a/workflows/manage.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: "Manage workflows" -description: "Enable, disable, trigger, and delete workflows from your dashboard. Configure GitHub or GitLab triggers, schedules, context repos, and automerge." -keywords: ["cron", "push", "automerge", "context", "workflow instructions", "trigger", "disable workflow", "enable workflow"] ---- - -import GitlabWorkflowSetup from '/snippets/gitlab-workflow-setup.mdx'; - -## Prerequisites - -- A Mintlify project connected to a GitHub or GitLab repository -- For GitHub: the [Mintlify GitHub App](/deploy/github) installed on every repository you plan to use in the workflow -- For GitLab: a connected GitLab account (see [GitLab setup](#gitlab-setup) below) - - - You can also create, list, and delete workflows from the terminal with [`mint workflow`](/cli/commands#mint-workflow). The CLI is useful for scripting and CI; the dashboard is the easiest way to configure and monitor workflow runs. - - -## Enable a workflow - -1. Open the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page in your dashboard. -2. Click the toggle beside a workflow to enable it. - - The workflows dashboard. - The workflows dashboard. - - - If the workflow can run with default settings, it activates immediately. Otherwise, the settings panel opens so you can fill in any required configurations. - - The configuration options for a workflow. - The configuration options for a workflow. - -3. If the settings panel opens, fill in the required fields. -4. Click **Turn on workflow**. - -To change settings for an active workflow, click the settings button beside it. Use the toggle in the modal header to enable or disable the workflow without leaving the settings view. - -## Configurations - -### Trigger - -Each workflow has a default trigger that controls when it runs. To change the trigger, select a different option in the settings panel. - -- **Content update**: Runs whenever you push content to your project repository, including pull request merges and direct pushes. -- **Code change**: Runs when a pull request merges in a connected source code repository. You must specify at least one source repository. -- **Custom schedule**: Runs on a recurring schedule you define. Workflows queue within 10 minutes of the scheduled time. - -### Update mode - -Each workflow has a default mode for how it makes updates. Either directly merging changes into your content repository or opening a pull request for review. - -To require a review before the workflow updates your content, select **Require review** in the settings panel. - - - For GitHub repositories, automatic updates require the Mintlify GitHub App to have bypass permissions on every ruleset targeting 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 and requires at least the Maintainer role on each project. - - -### Context repositories - -For custom workflows and some predefined workflows, you can add context repositories—additional source code repositories the agent reads when the workflow runs. This is useful when your workflow prompt references code, APIs, or other content that lives outside your project repository. - -You can add up to 10 context repositories per workflow. For each GitHub repository, install the Mintlify GitHub App. Add repositories on the [GitHub App settings](https://app.mintlify.com/settings/organization/github-app) page. - -### Integrations - -For custom workflows and the **Update from code changes** workflow, you can enable connected [agent integrations](/agent/integrations) so the agent can pull context from tools like Slack, Notion, or Linear when the workflow runs. - -To enable integrations for a workflow, open its settings and select the integrations you want the agent to use in the **Available integrations** section. Only integrations already connected for your organization appear in the list. See [Agent integrations](/agent/integrations) for more information on connecting integrations. - -### Slack notifications - -Send Slack messages to one or more channels when workflows run. - -To enable Slack notifications: -1. Install the [Mintlify Slack app](/agent/slack) in your workspace. -2. Click **Turn on Slack notifications** on the [Workflows](https://app.mintlify.com/products/workflows) page of your dashboard. - - The turn on Slack notifications button. - The turn on Slack notifications button. - -3. Select one or more notification channels. -4. Click **Save changes**. - -Once enabled, Mintlify posts to the selected channels when: - -- A workflow opens a pull request for review. -- A workflow pull request has been waiting for review for three days. -- A workflow merges a pull request, or fails to complete. - -### Instructions - -Add optional instructions that append to the workflow's base prompt on every run. Use these to adjust the style, tone, or other project-specific behaviors without changing the core workflow logic. - -### Target languages - -When you enable the **Translate content** workflow, select one or more languages to keep in sync with your source content. - -- Mintlify reads the [languages](/organize/navigation#languages) defined in your `docs.json` to identify your default language and preselects any already configured target languages. -- You must select at least one target language to save the workflow. -- You cannot select the source language as a target. - -You can add target languages at any time by opening the workflow's settings and editing the **Translate to** field. - - - -## Disable a workflow - -1. Go to the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page in your dashboard. -2. Click the toggle beside a workflow to disable it. - -When you re-enable a scheduled workflow or change its schedule, Mintlify recalculates the next run time from the current time. Disabled workflows do not retain a pending run time. - -## View run history - -Each workflow keeps a log of past runs, including the status and a summary of changes made. - -1. Go to the [Workflow Runs](https://app.mintlify.com/products/workflows) page in your dashboard. -2. Use the dropdown menus to filter by specific workflows or status. - - Workflow runs page showing the workflow and status filters. - Workflow runs page showing the workflow and status filters. -