diff --git a/agent/index.mdx b/agent/index.mdx index 1573db889e..032ed9915e 100644 --- a/agent/index.mdx +++ b/agent/index.mdx @@ -29,7 +29,7 @@ Use the agent to: - Process and include images, diagrams, and other files from Slack attachments. - Search and revise code examples and API references across your docs. - Reference source code from any repository that has the Mintlify GitHub App installed. -- 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 aa98789ed7..20ffc96717 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 handle recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product. -See [Workflows](/workflows/index) for more information. +See [Automations](/automations/index) for more information. ## Automate with the API diff --git a/ai-native.mdx b/ai-native.mdx index 03b5327db7..2b8fd1e392 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/automations/create.mdx b/automations/create.mdx new file mode 100644 index 0000000000..e467d9428c --- /dev/null +++ b/automations/create.mdx @@ -0,0 +1,39 @@ +--- +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"] +--- + +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 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. The agent 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, when it runs, instructions, and how it makes updates. +4. Click **Create automation**. + +## Best practices + +Effective automation instructions focus on a single task and define a clear, verifiable outcome. Automations have some variance because agents are nondeterministic, but consistent instructions produce consistent results. + +- **Describe the outcome.** Tell the agent what the result should look like. Describe what done looks like. +- **Write a procedure.** Give the agent a step-by-step guide to follow. +- **Specify context.** Reference the files, directories, or repositories the agent should use. +- **Keep scope narrow.** Split complex tasks across multiple automations rather than combining them into one prompt. + + + Review the output of your custom automations to ensure they are working as expected. Update your instructions to improve the results. + + + diff --git a/automations/enable.mdx b/automations/enable.mdx new file mode 100644 index 0000000000..9366019d0a --- /dev/null +++ b/automations/enable.mdx @@ -0,0 +1,95 @@ +--- +title: "Enable automations" +description: "Enable automations on your Mintlify project. Configure GitHub or GitLab triggers, add context repositories, set schedules, and turn on automerge for the agent." +keywords: ["cron", "push trigger", "automerge"] +--- + +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 automation +- For GitLab: a connected GitLab account (see [GitLab setup](#gitlab-setup) below) + +## Enable automations + +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 modal opens so you can choose any required configurations. + + The configuration options for the codebase updates automation. + The configuration options for the codebase updates automation. + +3. If the modal opens, fill in the required fields and 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 repositories + +For automations that run on push events, specify the repositories to watch. You can specify up to 10 repositories per automation. + +For GitHub repositories, you must install the Mintlify GitHub App on each repository. Add repositories on the [GitHub app](https://app.mintlify.com/settings/organization/github-app) settings page. + +### Update mode + +Each automation has a default mode for how it makes updates, either by directly updating your content repository or by opening a pull request. + +If you want to require reviews before an automation updates your content, click **Require review**. + + + 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. + + +### Trigger + +Each automation has a default for when it runs, either in response to changes in your content repository, in response to changes in a trigger repository, or on a schedule. + +If you want to change the default, select a different trigger. + +### Instructions + +Add optional instructions appended to the automation's base prompt. Use these instructions to adjust the style, tone, or other aspects unique to your project. + +### Target languages + +When you enable the **Translate content** automation, select one or more languages you want 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 change the target languages at any time by opening the automation's settings and editing the **Translate to** field. + +#### Run a translation immediately + +After saving the automation, click **Translate now** to run it on demand using the currently saved target languages. The automation must be enabled to trigger a manual run. Manual runs do not affect the automation's regular trigger. + +## Improve docs from assistant chats + +The **Improve docs from assistant chats** automation reviews recent trends in [assistant](/assistant/index) questions and opens targeted documentation updates that address gaps your users hit. + +Use this automation when you want the agent to triage assistant activity for you and propose changes that answer the questions users actually ask. + +This automation runs on a schedule. It does not require trigger repositories or extra context configuration. Enable it from the [Automations](https://app.mintlify.com/products/automations) page and pick whether updates merge automatically or open a pull request for review. + +## Improve docs from feedback + +The **Improve docs from feedback** automation reviews recent [page feedback](/optimize/feedback) and opens targeted documentation updates based on the issues users report. + +Use this automation when you collect thumbs ratings or contextual feedback and want the agent to convert that signal into concrete docs changes. + +When a run completes, the run detail in your dashboard includes the specific feedback citations the agent used. Each citation links to the feedback in your [analytics dashboard](https://app.mintlify.com/products/analytics/v2/feedback) so you can verify the context that drove the update. + +This automation runs on a schedule and requires that feedback collection is enabled on the [Add-ons](https://app.mintlify.com/products/addons) page. It does not require trigger repositories or extra context configuration. + + diff --git a/automations/index.mdx b/automations/index.mdx new file mode 100644 index 0000000000..9682cde819 --- /dev/null +++ b/automations/index.mdx @@ -0,0 +1,30 @@ +--- +title: "Automations overview" +sidebarTitle: "Overview" +description: "Automate documentation 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 pushes to 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 clones any specified repositories as context and follows the prompt. + + +Use automations that run on a schedule to automate recurring tasks, like publishing changelogs or checking for grammar and style issues. + +Use automations that run on push events to automate reactive maintenance tasks, like updating API reference documentation or identifying documentation updates needed for new features. + + +## Trigger types + +Automations support two trigger types. + +- **Schedule (cron)** — Run on a recurring daily, weekly, or monthly schedule. Automations queue within 10 minutes of the scheduled time. +- **Push events** — Run when changes push to a specific repository or branch, including pull request merges and direct pushes. + +You cannot combine trigger types in a single automation. Each automation has exactly one trigger. + +## Usage limits + +Each automation can run up to 500 times per day. Hobby plan projects have an additional limit of 100 total automation runs per month. Runs that fail do not count towards these limits. diff --git a/automations/manage.mdx b/automations/manage.mdx new file mode 100644 index 0000000000..66ad5722ea --- /dev/null +++ b/automations/manage.mdx @@ -0,0 +1,32 @@ +--- +title: "Manage automations" +description: "Trigger, disable, re-enable, and delete Mintlify automations from your dashboard, and learn how schedules recalculate after you pause and resume an automation." +keywords: ["manage automations", "trigger automation", "disable automation", "enable automation"] +--- + +## 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, Mintlify recalculates the next run time from the current time. + +## 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**. + +## View run history + +Each automation keeps a log of past runs, including the status and a summary of changes made. + +1. Go to the [Automations](https://app.mintlify.com/products/automations) page in your dashboard. +2. Click an automation. +3. Use the dropdown menus to filter by specific automations or status. + + Automation runs with the status filter menu open. + Automation runs with the status filter menu open. + diff --git a/changelog.mdx b/changelog.mdx index e92b27282e..2da8d75961 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -18,7 +18,7 @@ noindex: true ## Workflows - - New **Improve content from assistant conversations** workflow reviews trends from user questions and suggests documentation updates to address gaps. See [Workflows](https://www.mintlify.com/docs/workflows/enable#improve-docs-from-assistant-chats). + - New **Improve content from assistant conversations** workflow reviews trends from user questions and suggests documentation updates to address gaps. See [Workflows](https://www.mintlify.com/docs/automations/enable#improve-docs-from-assistant-chats). - **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. @@ -93,13 +93,13 @@ noindex: true ## Workflows - Workflows have been rebuilt with a new [dashboard experience](https://app.mintlify.com/products/workflows?tab=workflows). + Workflows 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. - See the [workflows](/workflows) documentation for more details. + See the [workflows](/automations) documentation for more details. ## Editor @@ -215,7 +215,7 @@ noindex: true ## GitLab OAuth for workflows - [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. + [Workflows](/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 workflows. The agent opens merge requests on GitLab just like it opens pull requests on GitHub. ## Improvements @@ -281,7 +281,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. + - [Workflows](/automations) now surface in the dashboard inbox for easier tracking. The workflow 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. @@ -319,7 +319,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. + - [Workflows](/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. @@ -333,7 +333,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 [workflow](/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. @@ -445,11 +445,11 @@ noindex: true ## Workflow 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 [workflows](/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 - 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 [workflows](/automations) files from the command line with the `mint workflow` CLI command. Interactive prompts guide you through name, trigger, context, and instructions. ## Agent API v2 @@ -527,7 +527,7 @@ noindex: true ## Workflows - 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 [workflows](/automations). Set up scheduled or event-triggered automations that run the agent to update your documentation. Workflows are in beta and currently available on [Enterprise plans](https://mintlify.com/pricing). Available on Pro plans soon. diff --git a/dashboard/audit-logs.mdx b/dashboard/audit-logs.mdx index 4873d5ac87..d7100bcb4c 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/github.mdx b/deploy/github.mdx index b0b513da61..66092496df 100644 --- a/deploy/github.mdx +++ b/deploy/github.mdx @@ -92,7 +92,7 @@ Read and write permissions: ## Manage repository access -When installing the GitHub App, you can grant access to all of your repositories or specific ones. Grant access only to your documentation repository and any repositories that you want to provide as context for the agent or workflows. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new). +When installing the GitHub App, you can grant access to all of your repositories or specific ones. Grant access only to your documentation repository and any repositories that you want to provide as context for the agent or automations. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new). ## Configure docs source diff --git a/deploy/gitlab-self-hosted.mdx b/deploy/gitlab-self-hosted.mdx index 0d1f7a9e78..5838ebc981 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 90e6846eb9..6160e5b1bc 100644 --- a/docs.json +++ b/docs.json @@ -112,12 +112,12 @@ }, "ai/mintlify-mcp", { - "group": "Workflows", - "root": "workflows/index", + "group": "Automations", + "root": "automations/index", "pages": [ - "workflows/enable", - "workflows/create", - "workflows/manage" + "automations/enable", + "automations/create", + "automations/manage" ] }, { diff --git a/guides/configure-automerge.mdx b/guides/configure-automerge.mdx index 06faae7795..2b3e3adbe0 100644 --- a/guides/configure-automerge.mdx +++ b/guides/configure-automerge.mdx @@ -1,14 +1,14 @@ --- title: "Configure automerge for GitHub Apps" sidebarTitle: "Configure automerge" -description: "Set up GitHub workflows to automatically merge Mintlify pull requests by adding the Mintlify bot to your repository's ruleset bypass list." +description: "Set up automations to automatically merge Mintlify pull requests by adding the Mintlify bot to your repository's ruleset bypass list." 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 dcbaac8f94..6865623dda 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 06268dcce3..30e9ee8ae8 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -15,7 +15,7 @@ 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. +- [Configure automerge](/guides/configure-automerge): Add the Mintlify GitHub App to a ruleset bypass list to enable automatic merging for automations. - [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 dfed3db3b0..b45ef1ec3c 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 @@ -317,7 +317,7 @@ If you work with your own translation vendors or regional translators, you can i This GitHub Actions workflow automatically exports changed English content for translation when PRs merge to main. -```yaml .github/workflows/export-for-translation.yml +```yaml .github/automations/export-for-translation.yml name: Export content for translation on: @@ -432,7 +432,7 @@ jobs: This GitHub Actions workflow validates and imports translated content when added via PR. -```yaml .github/workflows/import-translations.yml +```yaml .github/automations/import-translations.yml name: Import translations on: diff --git a/guides/maintenance.mdx b/guides/maintenance.mdx index 44659b330f..4497cec07b 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 cf2a5bf728..aed457b833 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 99cfc5bc98..03a009aa6b 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 9b96e30341..d1d083375d 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 an [automation](/automations) to run a style audit on a schedule or whenever changes push to your docs repository. ## Frequently asked questions diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 30694bf038..d32cf4a6e6 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 74ddca5450..b353a0c9f3 100644 --- a/redirects.json +++ b/redirects.json @@ -417,15 +417,23 @@ }, { "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": "/workflows", + "destination": "/automations/index" + }, + { + "source": "/workflows/:page", + "destination": "/automations/:page" }, { "source": "/agent/quickstart", diff --git a/what-is-mintlify.mdx b/what-is-mintlify.mdx index d07a265a14..3d8f34725a 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 46ac1201f9..0000000000 --- a/workflows/create.mdx +++ /dev/null @@ -1,39 +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"] ---- - -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. The agent 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, when it runs, instructions, and how it makes updates. -4. Click **Create workflow**. - -## Best practices - -Effective workflow instructions focus on a single task and define a clear, verifiable outcome. Workflows have some variance because agents are nondeterministic, but consistent instructions produce consistent results. - -- **Describe the outcome.** Tell the agent what the result should look like. Describe what done looks like. -- **Write a procedure.** Give the agent a step-by-step guide to follow. -- **Specify context.** Reference the files, directories, or repositories the agent should use. -- **Keep scope narrow.** Split complex tasks across multiple workflows rather than combining them into one prompt. - - - Review the output of your custom workflows to ensure they are working as expected. Update your instructions to improve the results. - - - diff --git a/workflows/enable.mdx b/workflows/enable.mdx deleted file mode 100644 index a3b62a6464..0000000000 --- a/workflows/enable.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Enable workflows" -description: "Enable workflows on your Mintlify project. Configure GitHub or GitLab triggers, add context repositories, set schedules, and turn on automerge for the agent." -keywords: ["cron", "push trigger", "automerge"] ---- - -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) - -## Enable workflows - -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 modal opens so you can choose any required configurations. - - The configuration options for the codebase updates workflow. - The configuration options for the codebase updates workflow. - -3. If the modal opens, fill in the required fields and 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 repositories - -For workflows that run on push events, specify the repositories to watch. You can specify up to 10 repositories per workflow. - -For GitHub repositories, you must install the Mintlify GitHub App on each repository. Add repositories on the [GitHub app](https://app.mintlify.com/settings/organization/github-app) settings page. - -### Update mode - -Each workflow has a default mode for how it makes updates, either by directly updating your content repository or by opening a pull request. - -If you want to require reviews before a workflow updates your content, click **Require review**. - - - 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. - - -### Trigger - -Each workflow has a default for when it runs, either in response to changes in your content repository, in response to changes in a trigger repository, or on a schedule. - -If you want to change the default, select a different trigger. - -### Instructions - -Add optional instructions appended to the workflow's base prompt. Use these instructions to adjust the style, tone, or other aspects unique to your project. - -### Target languages - -When you enable the **Translate content** workflow, select one or more languages you want 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 change the target languages at any time by opening the workflow's settings and editing the **Translate to** field. - -#### Run a translation immediately - -After saving the workflow, click **Translate now** to run it on demand using the currently saved target languages. The workflow must be enabled to trigger a manual run. Manual runs do not affect the workflow's regular trigger. - -## Improve docs from assistant chats - -The **Improve docs from assistant chats** workflow reviews recent trends in [assistant](/assistant/index) questions and opens targeted documentation updates that address gaps your users hit. - -Use this workflow when you want the agent to triage assistant activity for you and propose changes that answer the questions users actually ask. - -This workflow runs on a schedule. It does not require trigger repositories or extra context configuration. Enable it from the [Workflows](https://app.mintlify.com/products/workflows?tab=workflows) page and pick whether updates merge automatically or open a pull request for review. - -## Improve docs from feedback - -The **Improve docs from feedback** workflow reviews recent [page feedback](/optimize/feedback) and opens targeted documentation updates based on the issues users report. - -Use this workflow when you collect thumbs ratings or contextual feedback and want the agent to convert that signal into concrete docs changes. - -When a run completes, the run detail in your dashboard includes the specific feedback citations the agent used. Each citation links to the feedback in your [analytics dashboard](https://app.mintlify.com/products/analytics/v2/feedback) so you can verify the context that drove the update. - -This workflow runs on a schedule and requires that feedback collection is enabled on the [Add-ons](https://app.mintlify.com/products/addons) page. It does not require trigger repositories or extra context configuration. - - diff --git a/workflows/index.mdx b/workflows/index.mdx deleted file mode 100644 index 12bf7c1d13..0000000000 --- a/workflows/index.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Workflows overview" -sidebarTitle: "Overview" -description: "Automate documentation 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 pushes to 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 clones any specified repositories as context and follows the prompt. - - -Use workflows that run on a schedule to automate recurring tasks, like publishing changelogs or checking for grammar and style issues. - -Use workflows that run on push events to automate reactive maintenance tasks, like updating API reference documentation or identifying documentation updates needed for new features. - - -## Trigger types - -Workflows support two trigger types. - -- **Schedule (cron)** — Run on a recurring daily, weekly, or monthly schedule. Workflows queue within 10 minutes of the scheduled time. -- **Push events** — Run when changes push to a specific repository or branch, including pull request merges and direct pushes. - -You cannot combine trigger types in a single workflow. Each workflow has exactly one trigger. - -## Usage limits - -Each workflow can run up to 500 times per day. Hobby plan projects have an additional limit of 100 total workflow runs per month. Runs that fail do not count towards these limits. diff --git a/workflows/manage.mdx b/workflows/manage.mdx deleted file mode 100644 index 91302e17bd..0000000000 --- a/workflows/manage.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Manage workflows" -description: "Trigger, disable, re-enable, and delete Mintlify workflows from your dashboard, and learn how schedules recalculate after you pause and resume a workflow." -keywords: ["manage workflows", "trigger workflow", "disable workflow", "enable workflow"] ---- - -## 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, Mintlify recalculates the next run time from the current time. - -## 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**. - -## View run history - -Each workflow keeps a log of past runs, including the status and a summary of changes made. - -1. Go to the [Workflows](https://app.mintlify.com/products/workflows) page in your dashboard. -2. Click a workflow. -3. Use the dropdown menus to filter by specific workflows or status. - - Workflow runs with the status filter menu open. - Workflow runs with the status filter menu open. -