### Install Mergify CLI and Setup Stacks Source: https://docs.mergify.com/stacks.md Install the Mergify CLI tool and set up Stacks for your repository. This is the initial setup for personal use. ```bash uv tool install mergify-cli mergify stack setup ``` -------------------------------- ### AI Agent Setup URL for Mergify Stacks Source: https://docs.mergify.com/stacks.md Provide this URL to your AI coding agent. The agent will use it to install the Mergify CLI and the Stacks skill. ```text https://docs.mergify.com/stacks/agents ``` -------------------------------- ### Install Mergify CLI with uv Source: https://docs.mergify.com/cli.md Use this command to install the Mergify CLI using the uv tool. Ensure uv is installed first. ```bash uv tool install mergify-cli ``` -------------------------------- ### Basic Condition Examples Source: https://docs.mergify.com/conditions These examples demonstrate simple conditions for matching milestones, file changes, and labels. ```yaml - milestone = v1.0 ``` ```yaml - "#files <= 50" ``` ```yaml - label != bug ``` -------------------------------- ### Install Mergify CLI with pipx Source: https://docs.mergify.com/cli.md Use this command to install the Mergify CLI using pipx. Ensure pipx is installed first. ```bash pipx install mergify-cli ``` -------------------------------- ### GitHub Actions: Install cargo2junit Source: https://docs.mergify.com/ci-insights/test-frameworks/rust.md Install `cargo2junit` within a GitHub Actions workflow using the `taiki-e/install-action`. ```yaml - name: Install cargo2junit uses: taiki-e/install-action@cargo2junit ``` -------------------------------- ### Install Vitest Reporter with pnpm Source: https://docs.mergify.com/ci-insights/test-frameworks/vitest.md Install the @mergifyio/vitest package as a development dependency using pnpm. ```bash pnpm add --save-dev @mergifyio/vitest ``` -------------------------------- ### Install Vitest Reporter with yarn Source: https://docs.mergify.com/ci-insights/test-frameworks/vitest.md Install the @mergifyio/vitest package as a development dependency using yarn. ```bash yarn add --dev @mergifyio/vitest ``` -------------------------------- ### Initialize Terraform Source: https://docs.mergify.com/integrations/terraform.md Run 'terraform init' after declaring the provider to download and install it. ```bash terraform init ``` -------------------------------- ### Install Vitest Reporter with npm Source: https://docs.mergify.com/ci-insights/test-frameworks/vitest.md Install the @mergifyio/vitest package as a development dependency using npm. ```bash npm install --save-dev @mergifyio/vitest ``` -------------------------------- ### After: Merge Protections Rule Example Source: https://docs.mergify.com/workflow/actions/post_check.md This example demonstrates the equivalent configuration using the recommended Merge Protections feature. It directly defines success and neutral conditions without an intermediate check-run. ```yaml merge_protections: - name: Check CI status if: - base=main success_conditions: - check-success=ci/test - check-neutral=ci/lint ``` -------------------------------- ### Backport Example Source: https://docs.mergify.com/commands/backport.md Example of using the backport command to apply changes from a merged pull request on 'main' to the 'v2.0-stable' branch. ```text @Mergifyio backport v2.0-stable ``` -------------------------------- ### Get a Mergify configuration simulation for a repository Source: https://docs.mergify.com/api/simulator Get a simulation of what Mergify will do for this repository. ```APIDOC ## POST `/repos/{owner}/{repository}/configuration-simulator` ### Description Get a simulation of what Mergify will do for this repository. ### Method POST ### Endpoint `/repos/{owner}/{repository}/configuration-simulator` ### Parameters #### Path Parameters - **owner** (string) - required - The owner of the repository - **repository** (string) - required - The name of the repository #### Request Body - **mergify_yml** (string) - required - A Mergify configuration ### Response #### Success Response (200) - **message** (string) - The message of the Mergify check run simulation - **deprecations** (DeprecationInfo[]) - Deprecation notices detected in the configuration - **message** (string) - Human-readable deprecation reason - **deadline** (string) - Date after which the deprecated configuration will be rejected - **path_to_field** (string[] | null) - Path to the deprecated field inside the configuration, or null when the deprecation is not tied to a specific field ### Request Example ```json { "mergify_yml": "string" } ``` ### Response Example ```json { "message": "The configuration is valid", "deprecations": [] } ``` ``` -------------------------------- ### Install Mergify CLI on macOS with Homebrew Source: https://docs.mergify.com/cli.md Install the Mergify CLI on macOS using Homebrew. This command first installs uv if not already present, then installs the CLI. ```bash brew install uv uv tool install mergify-cli ``` -------------------------------- ### Verify Mergify CLI Installation Source: https://docs.mergify.com/stacks/agents.md Run this command to verify that the Mergify CLI has been installed correctly. ```bash mergify --version ``` -------------------------------- ### GitHub Actions: Install cargo-nextest Source: https://docs.mergify.com/ci-insights/test-frameworks/rust.md Install `cargo-nextest` within a GitHub Actions workflow using the `taiki-e/install-action`. ```yaml - name: Install cargo-nextest uses: taiki-e/install-action@nextest ``` -------------------------------- ### Example: Multi-Language Monorepo Scopes Configuration Source: https://docs.mergify.com/merge-queue/scopes/file-patterns.md Configure scopes for a monorepo containing Python, JavaScript, and Go services, along with shared configuration files. This example shows how to define include patterns for different service types and shared resources. ```yaml scopes: source: files: python-api: include: - services/api/**/*.py - libs/python/**/*.py user-service: include: - services/users/**/*.go frontend: include: - apps/web/**/*.{js,jsx,ts,tsx} shared-config: include: - config/**/* - docker/**/* queue_rules: - name: default batch_size: 8 batch_max_wait_time: 5 min ``` -------------------------------- ### Install trx2junit Converter Source: https://docs.mergify.com/ci-insights/test-frameworks/mstest.md Install the trx2junit global tool to convert TRX test results files to JUnit format. ```bash dotnet tool install -g trx2junit ``` -------------------------------- ### Install cargo2junit Source: https://docs.mergify.com/ci-insights/test-frameworks/rust.md Install the cargo2junit tool to convert Rust test output to JUnit XML format. This is a prerequisite for using the `cargo test | cargo2junit` method. ```bash cargo install cargo2junit ``` -------------------------------- ### Example Request for Base Refs Source: https://docs.mergify.com/api/queues Example cURL request to fetch base branches affected by queue activity. Replace placeholders with your repository owner, name, and authentication token. ```bash curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/queues/branches" \ -H "Authorization: Bearer " ``` -------------------------------- ### Schedule Examples Source: https://docs.mergify.com/configuration/data-types.md Define schedules for automated actions. Examples show daily, time-based, and timezone-specific schedules, along with exclusion rules. Schedules can only use equality operators. ```yaml schedule = Mon-Fri ``` ```yaml schedule = 09:00-19:00 ``` ```yaml schedule = 09:00-19:00[America/Vancouver] ``` ```yaml schedule != Mon-Fri 09:00-19:00[America/Vancouver] ``` ```yaml schedule != SAT-SUN ``` -------------------------------- ### Link Header Example for Pagination Source: https://docs.mergify.com/api-usage This example demonstrates the format of the `Link` header used for cursor-based pagination in paginated responses. It includes links for navigating between pages. ```http Link: ; rel="next", ; rel="last", ; rel="first" ``` -------------------------------- ### Example GitHub Actions Step with MERGIFY_TOKEN Source: https://docs.mergify.com/ci-insights/test-frameworks/vitest.md An example of a GitHub Actions step that includes the MERGIFY_TOKEN environment variable for running tests. ```yaml - name: Run Tests ๐Ÿงช env: MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }} run: npm test ``` -------------------------------- ### Example: Copying to a Development Branch Source: https://docs.mergify.com/commands/copy.md This example demonstrates how to copy changes from the current pull request to the 'development' branch. Mergify will attempt to create a new pull request on the target branch. ```text @Mergifyio copy development ``` -------------------------------- ### Priority Rule Example Source: https://docs.mergify.com/configuration/data-types.md Example of defining priority rules based on conditions like base branch, labels, and check statuses. Priorities can be set using integers or aliases. ```yaml priority_rules: - name: my hotfix priority rule conditions: - base = main - label = hotfix - check-success = linters priority: high - name: my low priority rule conditions: - base = main - label = low - check-success = linters priority: 550 ``` -------------------------------- ### Install Mergify Stack Skill for Agents Supporting skills.sh Source: https://docs.mergify.com/stacks/setup.md Install the Mergify CLI skill for AI agents that support the skills.sh standard, such as Cursor or Cline. This enables them to interact with Mergify Stacks. ```bash npx skills add Mergifyio/mergify-cli ``` -------------------------------- ### Example Batch Bisection Statistics Response Source: https://docs.mergify.com/api/statistics Example JSON response structure for batch bisection statistics, showing started and completed bisection events with their associated details. ```json { "started": [ { "base_ref": "string", "partition_name": "string", "queue_name": "string", "priority_rule_name": "string", "stats": null } ], "completed": [ { "base_ref": "string", "partition_name": "string", "queue_name": "string", "priority_rule_name": "string", "stats": null } ] } ``` -------------------------------- ### Get Running Speculative Checks Statistics Source: https://docs.mergify.com/api/statistics Retrieve statistics on the number of speculative checks running on queues over time intervals. Requires repository owner and name. Optional parameters include base reference, partition name, queue name, start date, and end date. ```bash curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/stats/running_speculative_checks" \ -H "Authorization: Bearer " ``` -------------------------------- ### Graphite Workflow Example Source: https://docs.mergify.com/stacks/compare/graphite.md Demonstrates the sequence of commands used in the Graphite workflow for creating and submitting changes. ```bash gt create add-model # work on first change gt create add-endpoint # work on second change gt submit ``` -------------------------------- ### Mergify Stacks Workflow Example Source: https://docs.mergify.com/stacks/compare/graphite.md Illustrates the equivalent workflow using Mergify Stacks and Git commands for managing stacked changes. ```bash mergify stack new git commit -m "add model" git commit -m "add endpoint" mergify stack push ``` -------------------------------- ### Setup Flaky Test Detection with Buildkite Source: https://docs.mergify.com/ci-insights/setup/buildkite.md Configure a Buildkite pipeline to run tests multiple times for flaky test detection. This example runs tests 5 times (or as defined by RUN_COUNT) and exits with a failure code if any run fails. Ensure MERGIFY_TOKEN is set and CI Insights are enabled. ```yaml steps: - label: "Flaky test detection" command: | set +e failed=0 for i in $(seq $${RUN_COUNT:-5}); do echo "--- Run $$i of $${RUN_COUNT:-5}" pytest --junitxml=reports/junit-$$i.xml tests/ if [ $$? -ne 0 ]; then failed=1 fi done exit $$failed plugins: - mergifyio/mergify-ci#@@BUILDKITE_PLUGIN_VERSION@@: action: junit-process report_path: "reports/*.xml" token: "${MERGIFY_TOKEN}" ``` -------------------------------- ### Jenkins Job Setup for Flaky Test Detection (mergify cli upload) Source: https://docs.mergify.com/ci-insights/setup/jenkins.md Configure a Jenkins pipeline to run tests multiple times and upload results using 'mergify cli upload' for flaky test detection. This example uses a cron trigger and processes multiple test result files. ```groovy pipeline { agent any environment { MERGIFY_TOKEN = credentials('MERGIFY_TOKEN') RUN_COUNT = '5' } triggers { cron('0 H/12 * * 1-5') // Every 12 hours, Monday to Friday } stages { stage('Test') { steps { sh ''' # Run your test suite multiple times to detect flakiness set +e for i in $(seq "$RUN_COUNT"); do pytest tests/ # Run your test command with unique output file, e.g.: # npm test -- --reporters=default --reporters=jest-junit --outputFile=test-results-$i.xml done set -e # Quote the glob so Mergify expands it rather than the shell โ€” # recommended when many reports match. mergify ci junit-process 'test-results-*.xml' ''' } } } } ``` -------------------------------- ### gh-stack Workflow Example Source: https://docs.mergify.com/stacks/compare/gh-stack.md Demonstrates the typical command sequence for managing stacked PRs using the gh-stack CLI, involving initialization, adding changes, pushing, and submitting. ```bash gh stack init # work on first change gh stack add # work on second change gh stack push gh stack submit ``` -------------------------------- ### Get Repository Batch Size Statistics Source: https://docs.mergify.com/api/statistics Retrieve statistics on the batch size of checks running on queues over time intervals. Requires repository owner and name. Optional parameters include base reference, partition name, queue name, priority rule name, start date, and end date. ```bash curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/stats/batch_size" \ -H "Authorization: Bearer " ``` -------------------------------- ### Get Repository Queue Size Statistics Source: https://docs.mergify.com/api/statistics Retrieve the average, maximum, and minimum queue size over specified time intervals. Requires repository owner and name. Optional parameters include base reference, partition name, queue name, priority rule name, start date, and end date. ```bash curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/stats/queue_size" \ -H "Authorization: Bearer " ``` -------------------------------- ### Equivalent Configuration Without Defaults Source: https://docs.mergify.com/configuration/file-format.md This example shows the expanded configuration equivalent to the one using the `defaults` section, illustrating how default values are applied when not explicitly set. ```yaml pull_request_rules: - name: comment with default conditions: - label = comment actions: comment: message: I ๐Ÿ’™ Mergify bot_account: Autobot queue_rules: - name: default batch_size: 10 - name: default with smaller batch batch_size: 2 ``` -------------------------------- ### Manage default enabled products Source: https://docs.mergify.com/api/products Configure the list of products that will be enabled by default for all new repositories created under the specified owner. This streamlines the setup process for new projects. ```APIDOC ## PUT /default_products/{owner} ### Description Manage default enabled products for new repositories. ### Method PUT ### Endpoint `/default_products/{owner}` ### Parameters #### Path Parameters - **owner** (string) - required - The owner of the repository #### Request Body - **products** (array) - required - A list of products to set as default. Possible values include "ci_insights", "merge_protections", "workflow_automation", "merge_queue". ### Request Example ```json { "products": [ "ci_insights" ] } ``` ### Response #### Success Response (204) No content. #### Error Responses - 403 Forbidden - 404 Not found - 409 Conflict - 422 Unprocessable entity ``` -------------------------------- ### Install rspec-mergify Gem Source: https://docs.mergify.com/ci-insights/test-frameworks/rspec.md Install the rspec-mergify gem directly using the gem install command. ```bash gem install rspec-mergify ``` -------------------------------- ### Get a Mergify simulation for a repository Source: https://docs.mergify.com/api/simulator Get a simulation of what Mergify will do for this repository. ```APIDOC ## POST `/repos/{owner}/{repository}/simulator` ### Description Get a simulation of what Mergify will do for this repository. ### Method POST ### Endpoint `/repos/{owner}/{repository}/simulator` ### Parameters #### Path Parameters - **owner** (string) - required - The owner of the repository - **repository** (string) - required - The name of the repository #### Request Body - **mergify_yml** (string) - required - A Mergify configuration ### Response #### Success Response (200) - **title** (string) - The title of the Mergify check run simulation - **summary** (string) - The summary of the Mergify check run simulation - **deprecations** (DeprecationInfo[]) - Deprecation notices detected in the configuration - **message** (string) - Human-readable deprecation reason - **deadline** (string) - Date after which the deprecated configuration will be rejected - **path_to_field** (string[] | null) - Path to the deprecated field inside the configuration, or null when the deprecation is not tied to a specific field ### Request Example ```json { "mergify_yml": "string" } ``` ### Response Example ```json { "title": "string", "summary": "string", "deprecations": [ { "message": "string", "deadline": "2024-01-15", "path_to_field": null } ] } ``` ``` -------------------------------- ### Migration Example: Before Source: https://docs.mergify.com/merge-protections/auto-merge.md This YAML configuration demonstrates the 'before' state for migrating from the deprecated `autoqueue` feature to `auto_merge_conditions`. ```yaml queue_rules: - name: dependencies autoqueue: true queue_conditions: - author = dependabot[bot] merge_conditions: - check-success = ci - name: default queue_conditions: - check-success = ci ``` -------------------------------- ### Install Jest JUnit Reporter Source: https://docs.mergify.com/ci-insights/test-frameworks/jest.md Install the jest-junit package as a development dependency before configuring it. ```bash npm install --save-dev jest-junit ``` -------------------------------- ### Mergify Stacks Workflow Example Source: https://docs.mergify.com/stacks/compare/gh-stack.md Illustrates the Mergify Stacks workflow for managing stacked PRs, emphasizing the use of `mergify stack new` and standard Git commits, followed by `mergify stack push`. ```bash mergify stack new git commit -m "first change" git commit -m "second change" mergify stack push ``` -------------------------------- ### Get SVG badge Source: https://docs.mergify.com/api/badges Get badge in SVG image format. This endpoint is deprecated. ```APIDOC ## GET /badges/{owner}/{repository}.svg ### Description Get badge in SVG image format. ### Method GET ### Endpoint `/badges/{owner}/{repository}.svg` ### Parameters #### Path Parameters - **owner** (string) - Required - The owner of the repository - **repository** (string) - Required - The name of the repository #### Query Parameters - **style** (string) - Optional - The style of the button, more details on https://shields.io/. ### Responses #### Success Response (200) An SVG image. #### Error Responses - 403 Forbidden - 404 Not found - 409 Conflict - 422 Unprocessable entity ### Request Example ```bash curl -X GET "https://api.mergify.com/v1/badges/:owner/:repository.svg" ``` ``` -------------------------------- ### Get PNG badge Source: https://docs.mergify.com/api/badges Get badge in PNG image format. This endpoint is deprecated. ```APIDOC ## GET /badges/{owner}/{repository}.png ### Description Get badge in PNG image format. ### Method GET ### Endpoint `/badges/{owner}/{repository}.png` ### Parameters #### Path Parameters - **owner** (string) - Required - The owner of the repository - **repository** (string) - Required - The name of the repository #### Query Parameters - **style** (string) - Optional - The style of the button, more details on https://shields.io/. ### Responses #### Success Response (200) An PNG image. #### Error Responses - 403 Forbidden - 404 Not found - 409 Conflict - 422 Unprocessable entity ### Request Example ```bash curl -X GET "https://api.mergify.com/v1/badges/:owner/:repository.png" ``` ``` -------------------------------- ### Get a Mergify simulation for a pull request Source: https://docs.mergify.com/api/simulator Get a simulation of what Mergify will do on a pull request. ```APIDOC ## POST `/repos/{owner}/{repository}/pulls/{number}/simulator` ### Description Get a simulation of what Mergify will do on a pull request. ### Method POST ### Endpoint `/repos/{owner}/{repository}/pulls/{number}/simulator` ### Parameters #### Path Parameters - **owner** (string) - required - The owner of the repository - **repository** (string) - required - The name of the repository - **number** (integer) - required - The pull request number #### Request Body - **mergify_yml** (string) - required - A Mergify configuration ### Response #### Success Response (200) - **title** (string) - The title of the Mergify check run simulation - **summary** (string) - The summary of the Mergify check run simulation - **deprecations** (DeprecationInfo[]) - Deprecation notices detected in the configuration - **message** (string) - Human-readable deprecation reason - **deadline** (string) - Date after which the deprecated configuration will be rejected - **path_to_field** (string[] | null) - Path to the deprecated field inside the configuration, or null when the deprecation is not tied to a specific field ### Request Example ```json { "mergify_yml": "string" } ``` ### Response Example ```json { "title": "string", "summary": "string", "deprecations": [ { "message": "string", "deadline": "2024-01-15", "path_to_field": null } ] } ``` ``` -------------------------------- ### Validate Application Key Source: https://docs.mergify.com/api-usage This example demonstrates how to authenticate using an Application Key and retrieve your application's information. ```APIDOC ## GET /application ### Description Retrieves information about the authenticated application. ### Method GET ### Endpoint https://api.mergify.com/v1/application ### Parameters #### Headers - **Accept** (string) - Required - `application/json` - **Authorization** (string) - Required - `Bearer ` ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the application. - **name** (string) - The name of the application. - **github_account** (object) - Information about the associated GitHub account. - **id** (integer) - The GitHub account ID. - **login** (string) - The GitHub account login name. - **type** (string) - The type of GitHub account (e.g., 'Organization', 'User'). ### Response Example ```json { "id": 123, "name": "my application", "github_account": { "id": 123, "login": "Mergify", "type": "Organization" } } ``` ``` -------------------------------- ### Get shields.io badge config Source: https://docs.mergify.com/api/badges Get shields.io badge JSON configuration. This endpoint is deprecated. ```APIDOC ## GET /badges/{owner}/{repository} ### Description Get shields.io badge JSON configuration. ### Method GET ### Endpoint `/badges/{owner}/{repository}` ### Parameters #### Path Parameters - **owner** (string) - Required - The owner of the repository - **repository** (string) - Required - The name of the repository ### Responses #### Success Response (200) The shields.io badge JSON configuration. #### Error Responses - 403 Forbidden - 404 Not found - 409 Conflict - 422 Unprocessable entity ### Request Example ```bash curl -X GET "https://api.mergify.com/v1/badges/:owner/:repository" ``` ``` -------------------------------- ### Get shields.io Badge Config Source: https://docs.mergify.com/api/badges Get the JSON configuration for a shields.io badge. This endpoint is deprecated. ```curl curl -X GET "https://api.mergify.com/v1/badges/:owner/:repository" ``` -------------------------------- ### Manage Default Enabled Products Source: https://docs.mergify.com/api/products Use this endpoint to set the default products that will be enabled for all new repositories under a specific owner. Requires the repository owner. ```curl curl -X PUT "https://api.mergify.com/v1/default_products/:owner" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "products": [ "ci_insights" ] }' ``` -------------------------------- ### Buildkite Static Pipeline Entry Point Source: https://docs.mergify.com/monorepo-ci/buildkite.md This YAML configuration defines the initial steps in a Buildkite pipeline. It includes a 'Detect scopes' step using the Mergify CI plugin and a 'Upload conditional steps' step that executes a dynamic script. ```yaml # .buildkite/pipeline.yml steps: - label: ":mag: Detect scopes" key: detect-scopes plugins: - mergifyio/mergify-ci#@@BUILDKITE_PLUGIN_VERSION@@: action: scopes token: "${MERGIFY_TOKEN}" - label: ":pipeline: Upload conditional steps" depends_on: detect-scopes command: .buildkite/dynamic-pipeline.sh | buildkite-agent pipeline upload ``` -------------------------------- ### Timestamp Condition Example Source: https://docs.mergify.com/configuration/data-types.md Example of using a timestamp in a Mergify condition to check if a base branch has been updated. ```yaml - name: end of life version 10.0 conditions: - base = stable/10.0 - updated-at <= 2021-04-05 actions: comment: message: | The pull request needs to be rebased after end of life of version 10.0 ``` -------------------------------- ### Create a Time-Bounded Freeze (CLI) Source: https://docs.mergify.com/merge-protections/freeze.md Create a freeze with a specified start and end time in UTC. Include a reason for the freeze. ```bash mergify freeze create \ --reason "Release stabilization" \ --timezone UTC \ --start 2024-01-15T18:00:00 \ --end 2024-01-15T22:00:00 ``` -------------------------------- ### Curl Request for Stacks Adoption Summary Source: https://docs.mergify.com/api/stacks Example cURL command to fetch the adoption summary metrics for Mergify Stacks. Ensure you replace `` with your actual authorization token. ```bash curl -X GET "https://api.mergify.com/v1/repos/:owner/stacks/summary" \ -H "Authorization: Bearer " ```