From fbf4750d75ddb6e6a4548c9264f3e5d0e1ad2f36 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Fri, 28 Aug 2026 15:25:43 +0200 Subject: [PATCH] feat(docs): tell agents what Mergify is for in llms.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `llms.txt` was a page index and nothing else: an agent could see every URL we publish and still not know whether Mergify was the right tool for the task in front of it, or how to call it. Add two sections above the index. "When to use Mergify" names the jobs concretely — keeping main green, merging at volume without the CI bill, diagnosing CI, flaky tests, merge requirements GitHub cannot express, stacked PRs — and, just as usefully, says what is out of scope. GitHub only, no other code host; GitLab appears solely as a source of CI results. That one line saves an agent from planning an integration that does not exist, which is worth more than another paragraph of capabilities. "For agents" points at the machine-readable surfaces: the `.md` twin of every page and the `Accept: text/markdown` equivalent, the OpenAPI document with its base URL and auth scheme, the sitemap, the `.mergify.yml` JSON Schema, and how to install the CLI. That last one because naming a CLI without an install path leaves an agent exactly where it started; the paths are the Homebrew tap, the install script and the Windows release zip, per /cli/usage. Change-Id: I03f7b473ced0969e850d78b48758e1849535062f --- src/pages/llms.txt.ts | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts index 56c1b8b079..7479f8cb11 100644 --- a/src/pages/llms.txt.ts +++ b/src/pages/llms.txt.ts @@ -2,6 +2,41 @@ import type { CollectionEntry } from 'astro:content'; import { allPages } from '~/content'; import navItems from '~/content/navItems'; +/** + * What Mergify is for, in the terms an agent needs to decide whether to reach + * for it. Deliberately concrete about the jobs and about what is out of scope: + * "GitHub only" saves an agent from planning a GitLab integration that does not + * exist, which is worth more than another paragraph of capabilities. + */ +const WHEN_TO_USE: string[] = [ + '## When to use Mergify', + '', + 'Mergify is a hosted platform for teams merging code on **GitHub**. Reach for it when the task is:', + '', + '- **Keeping the main branch green.** Pull requests are merged through a queue that revalidates each one against the latest main, so semantic conflicts between individually-green PRs are caught before they land.', + '- **Merging at high volume without a CI bill to match.** Speculative checks, batching and two-step CI trade queue depth against CI minutes.', + '- **Diagnosing slow or unreliable CI.** CI Insights reports job, runner and queue-time health across GitHub Actions, CircleCI, Jenkins, Buildkite, TeamCity and GitLab CI, and can auto-retry transient job failures.', + '- **Dealing with flaky tests.** Test Insights classifies tests as healthy, flaky or broken from rerun outcomes, catches new flakiness on the pull request, and can quarantine known-flaky tests.', + '- **Enforcing merge requirements GitHub cannot express.** Merge Protections evaluate conditions richer than branch protection rules.', + '- **Working on stacked pull requests.** The `mergify` CLI creates and keeps a stack of dependent PRs in sync.', + '', + 'Mergify does **not** host code, and it does **not** support GitLab, Bitbucket or any', + 'code host other than GitHub. GitLab CI is supported as a source of CI results only.', +]; + +/** How an agent should read these docs and call the API. */ +function howToRead(site: string): string[] { + return [ + '## For agents', + '', + `- Every page listed below links to its Markdown source, and each of them serves that source from its own URL too — append \`.md\` (\`${site}/merge-queue.md\`) or send \`Accept: text/markdown\`. The generated API and CLI references are HTML only.`, + `- The REST API is described by an OpenAPI 3.1 document at [${site}/openapi.json](${site}/openapi.json). Base URL \`https://api.mergify.com/v1\`; authenticate with \`Authorization: Bearer \`, using either an application key created in the dashboard (scopes: \`admin\`, \`ci\`) or a GitHub personal access token.`, + `- Full page list: [${site}/sitemap-index.xml](${site}/sitemap-index.xml).`, + `- The \`mergify\` CLI drives stacked pull requests and CI test-result upload from a terminal. Install it with \`brew install mergifyio/tap/mergify-cli\` on macOS, the install script on Linux, or the release zip on Windows — see [${site}/cli/usage](${site}/cli/usage), with the command reference at [${site}/cli](${site}/cli).`, + `- Configuration lives in \`.mergify.yml\` at the repository root; its JSON Schema is at [${site}/mergify-configuration-schema.json](${site}/mergify-configuration-schema.json).`, + ]; +} + /** * Auto-generated list of documentation pages for LLM consumption. * Uses the navigation structure (navItems) as the single source of truth for ordering & inclusion. @@ -65,6 +100,10 @@ export const GET = async () => { lines.push(''); lines.push(`> ${summary}`); lines.push(''); + lines.push(...WHEN_TO_USE); + lines.push(''); + lines.push(...howToRead(site)); + lines.push(''); for (const section of sections) { lines.push(`## ${section.title}`); lines.push('');