diff --git a/src/content/docs/api/usage.mdx b/src/content/docs/api/usage.mdx index 8d63c019ae..6a348b46f8 100644 --- a/src/content/docs/api/usage.mdx +++ b/src/content/docs/api/usage.mdx @@ -9,7 +9,7 @@ import applicationKeysToken from "../../images/api-intro/application_keys_token. import applicationKeysDelete from "../../images/api-intro/application_keys_delete.png" Mergify provides a RESTful API for integrating with your merge queues, CI -insights, and workflow automation. +Insights, and Workflow Automation. All API requests should be directed to: `https://api.mergify.com/v1` @@ -77,18 +77,18 @@ As an alternative to application keys, you can authenticate to the Mergify API using a **GitHub Personal Access Token (PAT)** as a Bearer token. This is useful when integrating with tools that already have a GitHub token available, such as CI environments or -the [Mergify CLI](/stacks). +the [Mergify CLI](/cli/usage). You must have logged in to the [Mergify dashboard](https://dashboard.mergify.com) at least once using GitHub OAuth before using this method. The PAT is only used to -verify your GitHub identity — all permissions are based on your Mergify +verify your GitHub identity: all permissions are based on your Mergify account, not the PAT's scopes. **Accepted token formats:** -- `ghp_*` — [classic personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) -- `github_pat_*` — [fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) +- `ghp_*`: [classic personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) +- `github_pat_*`: [fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) Example: @@ -100,7 +100,7 @@ curl -H "Accept: application/json" \ :::note The PAT is used solely for identity verification. The token's GitHub - scopes do not affect what you can access in the Mergify API — permissions + scopes do not affect what you can access in the Mergify API; permissions are determined by your Mergify user account and its associated organizations. ::: @@ -132,8 +132,8 @@ for navigating between pages. **Query parameters:** -- `per_page` — Number of items per page (1–100, default: 10) -- `cursor` — Opaque cursor for the current page. Extract this from the `Link` header; do not construct it manually. +- `per_page`: Number of items per page (1–100, default: 10) +- `cursor`: Opaque cursor for the current page. Extract this from the `Link` header; do not construct it manually. **Link header example:** @@ -145,10 +145,10 @@ Link: +mergify --token your_token_here ``` Each command lists the authentication and other options it accepts under its diff --git a/src/content/docs/integrations.mdx b/src/content/docs/integrations.mdx index 12f6a00a85..6630513e0e 100644 --- a/src/content/docs/integrations.mdx +++ b/src/content/docs/integrations.mdx @@ -29,7 +29,7 @@ import Monitoring from './integrations/_monitoring.mdx' -## Developers Tools +## Developer Tools diff --git a/src/content/docs/integrations/dependabot.mdx b/src/content/docs/integrations/dependabot.mdx index 329388c84a..5780951467 100644 --- a/src/content/docs/integrations/dependabot.mdx +++ b/src/content/docs/integrations/dependabot.mdx @@ -10,9 +10,8 @@ import IntegrationLogo from "../../../components/IntegrationLogo.astro" [Dependabot](https://github.com/features/security) helps you keep your dependencies up-to-date by automatically opening pull requests for outdated -dependencies. When combined with Mergify, you can automate parts of the process -even further, ensuring your projects stay current with minimal manual -intervention. +dependencies. When combined with Mergify, you can automate more of the +process. ## Automating Dependabot Pull Request Merges @@ -31,7 +30,7 @@ pull_request_rules: ## Filtering Dependabot PRs -Dependabot provides specific labels for the type of dependency update, such as +Mergify exposes condition attributes describing each Dependabot update: `dependabot-dependency-name`, `dependabot-dependency-type`, and `dependabot-update-type`. You can use these in your [merge protection](/merge-protections/custom-rules) conditions to filter which @@ -50,9 +49,9 @@ merge_protections: ## Batching Dependency Updates For projects where there are frequent updates to a large number of small -libraries, it's efficient to batch these updates together. Using Mergify's -merge queue feature, you can automatically batch and test these updates -together, reducing CI load and ensuring compatibility. +libraries, you can batch these updates together. Using Mergify's merge queue +feature, you can automatically batch and test these updates together, reducing +CI load and ensuring compatibility. For example, you could set up a merge queue to batch those PRs 10 by 10: @@ -70,7 +69,7 @@ queue_rules: By default, Dependabot will try to rebase its pull requests every time there's a new commit to the main branch. In high-velocity projects with a lot of -update, this can lead to unnecessary CI runs. It's recommended to disable +updates, this can lead to unnecessary CI runs. It's recommended to disable Dependabot's automatic rebase feature and instead rely on Mergify to queue and merge these updates efficiently. @@ -92,8 +91,8 @@ updates: ## Configuring `MERGIFY_TOKEN` for Dependabot If you use Mergify features that require a `MERGIFY_TOKEN` in your GitHub -Actions workflows — such as [CI Insights](/ci-insights/setup/github-actions) or -[Scopes](/merge-queue/scopes) — you need to add the token to your **Dependabot +Actions workflows, such as [CI Insights](/ci-insights/setup/github-actions) or +[Scopes](/merge-queue/scopes), you need to add the token to your **Dependabot secrets** in addition to your regular GitHub Actions secrets. Dependabot workflows run in a restricted environment and **cannot access regular @@ -111,10 +110,6 @@ To configure it: :::note This applies to any workflow that references `${{secrets.MERGIFY_TOKEN}}` - and runs on Dependabot pull requests — including scopes detection, CI Insights + and runs on Dependabot pull requests, including scopes detection, CI Insights test uploads, and any other Mergify CI integration. ::: - -With Mergify and Dependabot working together, you can ensure your project's -dependencies are always up-to-date with minimal effort, ensuring a smooth and -efficient update process. diff --git a/src/content/docs/integrations/gha.mdx b/src/content/docs/integrations/gha.mdx index a0cfcc4fdb..19d089ca1f 100644 --- a/src/content/docs/integrations/gha.mdx +++ b/src/content/docs/integrations/gha.mdx @@ -16,8 +16,8 @@ can also be referenced from your Mergify ## Prerequisites 1. You've set up GitHub Actions in your repository. If you're new to GitHub - Actions, their [official documentation](https://docs.github.com/en/actions) - provides comprehensive guides. + Actions, see their + [official documentation](https://docs.github.com/en/actions). 2. GitHub Actions is already configured to report job statuses to your pull requests. @@ -43,5 +43,5 @@ can also be referenced from your Mergify :::caution To match a GitHub Actions status check with `check-success`, use the job - name only — not the workflow name. + name only, not the workflow name. ::: diff --git a/src/content/docs/integrations/github.mdx b/src/content/docs/integrations/github.mdx index 5dbff9fdd0..51b36c2097 100644 --- a/src/content/docs/integrations/github.mdx +++ b/src/content/docs/integrations/github.mdx @@ -10,8 +10,8 @@ import githubIntegScreenshot from"../../images/integrations/github/integrations. -Mergify is fully integrated with GitHub and many functionalities requires -Mergify to be installed on your repositories. +Mergify is fully integrated with GitHub and many features require Mergify to +be installed on your repositories. ## Configuring Enabled Products @@ -20,14 +20,14 @@ clicking on `Integrations` and then on `GitHub / Configure`. GitHub Integration -First, this screens allows you to define which products are enabled by default +First, this screen allows you to define which products are enabled by default for new repositories where the Mergify GitHub App is installed. Then, you can add repositories by clicking on `Add Repository` and installing the Mergify GitHub App on them. :::note - Adding repository requires GitHub admin privileges. + Adding a repository requires GitHub admin privileges. ::: Finally, you can enable or disable any product for any repositories by checking diff --git a/src/content/docs/integrations/slack.mdx b/src/content/docs/integrations/slack.mdx index bbb19f8fcf..6a848aa805 100644 --- a/src/content/docs/integrations/slack.mdx +++ b/src/content/docs/integrations/slack.mdx @@ -11,11 +11,9 @@ import ciInsightsConfig from "../../images/integrations/slack/ci-insights.png" -Mergify offers comprehensive Slack integration, allowing you to receive -notifications about your development workflow directly in Slack. You can get -updates about Merge Queue activities, CI job completions, test quarantine -activity, and pull request events, keeping your team informed without leaving -Slack. +Mergify's Slack integration sends notifications about your development +workflow directly to Slack. You can get updates about Merge Queue activities, +CI job completions, test quarantine activity, and pull request events. ## Setting Up the Mergify Slack Integration @@ -155,7 +153,7 @@ Test Insights notifications are available on the same plans as the ## Pull Request Notifications via GitHub-Slack Integration In addition to native Mergify notifications, you can also receive Slack -notifications based on Mergify actions by leveraging the GitHub to Slack +notifications based on Mergify actions by using the GitHub to Slack integration. ### Setting Up GitHub-Slack Integration diff --git a/src/content/docs/integrations/terraform.mdx b/src/content/docs/integrations/terraform.mdx index 9645fb0bcc..a8a7bdb8a6 100644 --- a/src/content/docs/integrations/terraform.mdx +++ b/src/content/docs/integrations/terraform.mdx @@ -63,7 +63,7 @@ Tokens are read from, in priority order: The `GITHUB_TOKEN` fallback expects a **personal access token** (classic `ghp_*` or fine-grained `github_pat_*`). It is **not** the built-in `GITHUB_TOKEN` secret that GitHub Actions exposes to - workflows — that one is a short-lived installation token (`ghs_*`) + workflows. That one is a short-lived installation token (`ghs_*`) which the Mergify API does not accept. In CI, store a PAT or a Mergify application key in a dedicated secret (commonly `MERGIFY_TOKEN`). @@ -83,7 +83,7 @@ resource "mergify_repository_products" "monorepo" { } ``` -The `products` attribute is **declarative** — applying the resource +The `products` attribute is **declarative**: applying the resource sets the exact set of enabled products on the repository, removing any that are not listed. diff --git a/src/content/docs/stacks/agents.mdx b/src/content/docs/stacks/agents.mdx index bbf684cf19..a520f03894 100644 --- a/src/content/docs/stacks/agents.mdx +++ b/src/content/docs/stacks/agents.mdx @@ -1,6 +1,6 @@ --- title: Stacks for AI Agents -description: One-page bootstrap for AI coding agents — install the Mergify CLI and the Stacks skill. +description: One-page bootstrap for AI coding agents to install the Mergify CLI and the Stacks skill. --- import CliInstall from '~/components/CliInstall.astro'; diff --git a/src/content/docs/stacks/compare.mdx b/src/content/docs/stacks/compare.mdx index 421aa5cc37..360d7a31bc 100644 --- a/src/content/docs/stacks/compare.mdx +++ b/src/content/docs/stacks/compare.mdx @@ -6,8 +6,8 @@ description: Honest comparisons between Mergify Stacks and other stacked PR tool import DocsetGrid from '~/components/DocsetGrid/DocsetGrid.astro'; import Docset from '~/components/DocsetGrid/Docset.astro'; -Choosing a stacking tool matters. Each one makes different trade-offs around -workflow complexity, Git model, platform integration, and collaboration support. +Each stacking tool makes different trade-offs around workflow complexity, Git +model, platform integration, and collaboration support. These pages give you an honest look at how Mergify Stacks compares so you can pick what fits your team. diff --git a/src/content/docs/stacks/compare/gh-stack.mdx b/src/content/docs/stacks/compare/gh-stack.mdx index 2742393f21..43e6930d09 100644 --- a/src/content/docs/stacks/compare/gh-stack.mdx +++ b/src/content/docs/stacks/compare/gh-stack.mdx @@ -106,7 +106,7 @@ gh-stack, pushing and creating PRs are separate steps (`push` then `submit`). **Merge Queue depth.** Mergify's Merge Queue has [batching](/merge-queue/batches), [priority lanes](/merge-queue/priority), [speculative checks](/merge-queue/performance#parallel-checks), and -[queue freeze](/merge-queue/pause). gh-stack relies on GitHub's built-in merge +[queue pause](/merge-queue/pause). gh-stack relies on GitHub's built-in merge queue, which is more limited. **Collaboration support.** `mergify stack checkout` lets a teammate pick up diff --git a/src/content/docs/stacks/compare/graphite.mdx b/src/content/docs/stacks/compare/graphite.mdx index 3528315c6a..167c5a2ff1 100644 --- a/src/content/docs/stacks/compare/graphite.mdx +++ b/src/content/docs/stacks/compare/graphite.mdx @@ -92,7 +92,7 @@ between them with `gt up`, `gt down`, `gt top`, and `gt bottom`. | Branch naming | Auto-generated ([configurable](/stacks/concepts#branch-mapping)) | Developer-chosen | | Alternate base branch | `mergify stack new --base ` | Multi-trunk support | | IDE integration | CLI only | VS Code extension | -| MCP for AI agents | Bundled with CLI | `gt mcp` | +| AI agent integration | [Skills](/stacks/agents) for Claude Code and skills.sh agents | `gt mcp` | | Merge Queue | [Native Mergify integration](/merge-queue) | Graphite merge queue | | Merge a stack | Bottom-up via Merge Queue | `gt merge` (stack-aware) | @@ -113,7 +113,7 @@ splits the flow across several operations (`gt create`, `gt modify`, **Merge Queue depth.** Mergify's Merge Queue has [batching](/merge-queue/batches), [priority lanes](/merge-queue/priority), [speculative checks](/merge-queue/performance#parallel-checks), and -[queue freeze](/merge-queue/pause). Graphite has a merge queue too; Mergify's +[queue pause](/merge-queue/pause). Graphite has a merge queue too; Mergify's is more configurable and has been in production longer. **No one else needs Mergify.** Only the stack author installs the CLI. @@ -170,7 +170,7 @@ Mergify has invested in a different direction: [Workflow Automation](/workflow). - **Merge Queue maturity**: batching, priority lanes, speculative checks, - queue freeze. + queue pause. - **CI and test intelligence**: [CI Insights](/ci-insights) for cost and timing analytics, flaky test detection, quarantine, and test reporting.