> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a CI skip plan for a Buildkite pipeline

> Requires the **Generate Dynamic CI plans** permission.

As [`dynamicCi.generatePlan`](#tag/dynamicCi/operation/dynamicCi.generatePlan), for a Buildkite pipeline. Identical request and response but for the workflow identity: Buildkite has no workflow file, so the pipeline is named by the organization and pipeline slugs its agent exports, and `jobKeys` are step `key:` values.

**Fail open.** A job absent from `jobs` must be run — that is the contract, not an error. Treat any non-200 the same way.

Send the changed files as `changedFiles` when you can compute them. Without it, Trunk fetches the diff between `baseSha` and `commitSha` through your GitHub App installation, which needs both commits on GitHub.



## OpenAPI

````yaml /openapi-v2.json post /v2/dynamic-ci/generate-buildkite-plan
openapi: 3.1.0
info:
  title: Trunk API
  version: 2.0.0
  description: >-
    The Trunk public API. Every endpoint is scoped to a single organization and
    requires a credential.


    ## Authentication


    For automation, send an API key as `Authorization: Bearer <key>`. An
    organization admin creates one in the Trunk app under **Settings → Developer
    → API Keys**, and chooses the permissions it holds. A key with no
    permissions can read merge queues but change nothing in them. Each write's
    description names the permission it needs, if any. Permissions cover merge
    queues and test-result uploads, including the quarantine lookups a CI run
    makes before it uploads; any key can call the other Flaky Tests and Dynamic
    CI endpoints, including their writes.


    A short-lived token in the `x-trunk-token` header is what Trunk's own tools
    send, such as the `trunk` CLI after `trunk auth login`. Your own
    integrations should use an API key.


    A GitHub Actions job can upload and read impacted targets with no Trunk
    secret: the `trunk-io/login` action exchanges the run's own GitHub
    credential (its OIDC token, or on a pull request from a fork its
    `GITHUB_TOKEN`) for a short-lived first-party token. That token is accepted
    only by `PUT /v2/impacted-targets`, by `GET
    /v2/pull-requests/{id}/impacted-targets` and, on a fork pull request, by the
    Flaky Tests CLI endpoints. It works only for the run's own repository. On a
    fork pull request it works only for that pull request, and the upload works
    only for the pull request's head sha.


    ## Errors


    Errors from the API are an `ErrorResponse`: `{ "error": { "code", "message"
    } }`. Switch on `code`, which is stable; `message` is prose and may change
    at any time.


    Some responses don't have this shape. Trunk's edge answers `401`, `403` for
    some credential problems (including a request with no credential), `429`,
    and gateway errors such as `503` before the request reaches the API. The API
    itself answers `413` for a body over 512 KB and `504` for a request that
    runs past its time limit (usually 5 seconds), both as plain text. Read
    `error.code` only when the body is JSON with an `error` object, and
    otherwise branch on the status code.


    **An authorization denial on a read is reported as `404`, not `403`** —
    whether a resource exists must not leak across organizations, so a resource
    in another organization is indistinguishable from one that does not exist.
    `403 INSUFFICIENT_PERMISSIONS` means the credential is valid but is not
    permitted the action (or carries no organization).


    Every response from the API carries an `X-Request-Id` header; edge responses
    may not. Quote it in support requests.


    ## Rate limiting


    Most requests share one limit per organization (currently 100 requests per
    second), across every API key, user, and CLI session in it. Some requests
    have limits of their own and don't count toward it: `GET` requests on paths
    that start with `/v2/pull-requests`, `/v2/ci-jobs`, `/v2/ci-workflow-runs`,
    or `/v2/ci-failure-clusters` (5 per second per API key or user); the merge
    queue metrics endpoints (5 per second per organization); every request from
    a GitHub Actions login, which includes impacted-target uploads and reads and
    the Flaky Tests CLI endpoints on a fork pull request (10 per second per
    repository, and separately for its fork pull requests; the other limits in
    this list do not apply to it); test-result uploads (1000 per second per
    organization) and quarantine lookups (250 per second per organization).
    Exceeding a limit returns `429`; retry with backoff. The limit is enforced
    at the edge, which does not yet wrap its `429` in the `ErrorResponse`
    envelope or send `Retry-After`, so treat any `429` as rate limiting
    regardless of body.


    ## Compatibility


    Within v2, Trunk may add: new endpoints, new **optional** response fields,
    new members to any enum (including new `code` values, new queue-entry
    states, and new providers), and new optional request parameters. **Clients
    must tolerate values and fields they do not recognize** rather than failing
    closed — a client that switches exhaustively over an enum will break when a
    member is added. Removals and semantic changes require a new major version.


    ## Provider support


    Merge queues, verification runs and checks are **GitHub-only** today;
    `Check.provider` has a single member for that reason. `PUT
    /v2/impacted-targets` accepts GitHub and GitLab repositories. A GitHub
    Actions login (the `trunk-io/login` action, or `trunk auth login
    --github-actions`) uploads only for its own GitHub repository. The
    `Provider` enum lists values the repository index can store, not surfaces
    that are fully supported.


    ## Not yet available


    A pull request's numeric **position** in its queue is not exposed, and list
    responses are not ordered by queue position. `GET
    /v2/merge-queues/{id}/order` returns the order the engine will consider pull
    requests in, but an array index there is not a wait: use a pending entry's
    `directlyAhead` rather than counting, and `GET
    /v2/pull-requests/{id}/queue-entry-estimate` for when it is expected to
    merge (on queues that serve estimates). This API delivers no events of its
    own — poll it, or subscribe to [Merge Queue's
    webhooks](https://docs.trunk.io/merge-queue/webhooks). `Idempotency-Key` is
    not yet honored, so a mutation that times out must be reconciled by reading
    the resource back rather than blindly retried.
  contact:
    name: Trunk Support
    url: https://docs.trunk.io
servers:
  - url: https://api.trunk.io
    description: Production
security:
  - apiKey: []
  - trunkToken: []
tags:
  - name: mergeQueues
    x-group: Merge Queues
  - name: pullRequests
    x-group: Pull Requests
  - name: mergeQueueVerificationRuns
    x-group: Verification Runs
  - name: impactedTargets
    x-group: Impacted Targets
  - name: repositories
    x-group: Repositories
  - name: dynamicCi
    x-group: Dynamic CI
  - name: ciJobs
    x-group: CI Jobs
  - name: ciWorkflowRuns
    x-group: CI Workflow Runs
  - name: ciFailureClusters
    x-group: CI Failure Clusters
  - name: testCollections
    x-group: Test Collections
  - name: tests
    x-group: Tests
  - name: testUploads
    x-group: Test Uploads
  - name: detectionEvents
    x-group: Detection Events
  - name: monitors
    x-group: Monitors
  - name: monitorTests
    x-group: Monitor Tests
paths:
  /v2/dynamic-ci/generate-buildkite-plan:
    post:
      tags:
        - dynamicCi
      summary: Generate a CI skip plan for a Buildkite pipeline
      description: >-
        Requires the **Generate Dynamic CI plans** permission.


        As
        [`dynamicCi.generatePlan`](#tag/dynamicCi/operation/dynamicCi.generatePlan),
        for a Buildkite pipeline. Identical request and response but for the
        workflow identity: Buildkite has no workflow file, so the pipeline is
        named by the organization and pipeline slugs its agent exports, and
        `jobKeys` are step `key:` values.


        **Fail open.** A job absent from `jobs` must be run — that is the
        contract, not an error. Treat any non-200 the same way.


        Send the changed files as `changedFiles` when you can compute them.
        Without it, Trunk fetches the diff between `baseSha` and `commitSha`
        through your GitHub App installation, which needs both commits on
        GitHub.
      operationId: dynamicCi.generateBuildkitePlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildkitePlanRequest'
      responses:
        '200':
          description: The plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiPlan'
        '400':
          description: '`VALIDATION_FAILED` | `CI_HOST_UNSUPPORTED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                VALIDATION_FAILED:
                  summary: VALIDATION_FAILED
                  value:
                    error:
                      code: VALIDATION_FAILED
                      message: 'Invalid input: expected string, received undefined'
                CI_HOST_UNSUPPORTED:
                  summary: CI_HOST_UNSUPPORTED
                  value:
                    error:
                      code: CI_HOST_UNSUPPORTED
                      message: >-
                        Dynamic CI does not support the repository host
                        gitlab.example.com
        '401':
          description: >-
            `AUTHENTICATION_REQUIRED` | `INVALID_TOKEN`. A malformed, expired,
            or deleted credential. Trunk's edge usually answers this before the
            request reaches the API, with a body that is not this envelope
            (`{"error": "unauthorized: invalid api key"}` for a bad API key, or
            plain text for a bad `x-trunk-token`), so branch on the status. A
            request with no credential at all gets `403` from the edge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AUTHENTICATION_REQUIRED:
                  summary: AUTHENTICATION_REQUIRED
                  value:
                    error:
                      code: AUTHENTICATION_REQUIRED
                      message: No credential was supplied
                INVALID_TOKEN:
                  summary: INVALID_TOKEN
                  value:
                    error:
                      code: INVALID_TOKEN
                      message: The supplied token failed verification
        '403':
          description: '`INSUFFICIENT_PERMISSIONS`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INSUFFICIENT_PERMISSIONS:
                  summary: INSUFFICIENT_PERMISSIONS
                  value:
                    error:
                      code: INSUFFICIENT_PERMISSIONS
                      message: >-
                        The supplied credential is missing the required
                        permission
        '404':
          description: '`REPOSITORY_NOT_FOUND`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                REPOSITORY_NOT_FOUND:
                  summary: REPOSITORY_NOT_FOUND
                  value:
                    error:
                      code: REPOSITORY_NOT_FOUND
                      message: Repository not found
        '429':
          description: >-
            `RATE_LIMIT_EXCEEDED`. Trunk's edge answers this, and does not yet
            wrap it in the error envelope or send `Retry-After`: treat any `429`
            as rate limiting, whatever its body, and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RATE_LIMIT_EXCEEDED:
                  summary: RATE_LIMIT_EXCEEDED
                  value:
                    error:
                      code: RATE_LIMIT_EXCEEDED
                      message: Rate limit exceeded; retry with backoff
        '500':
          description: '`INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INTERNAL_ERROR:
                  summary: INTERNAL_ERROR
                  value:
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
        '502':
          description: '`UPSTREAM_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_ERROR:
                  summary: UPSTREAM_ERROR
                  value:
                    error:
                      code: UPSTREAM_ERROR
                      message: An upstream service did not respond
components:
  schemas:
    BuildkitePlanRequest:
      type: object
      properties:
        repo:
          $ref: '#/components/schemas/PlanRepo'
        commitSha:
          type: string
          description: The commit being built — `BUILDKITE_COMMIT`.
          example: 9f2c1b7c2b4c9d1e0a3f5b6c7d8e9f0a1b2c3d4e
        baseSha:
          type:
            - string
            - 'null'
          description: >-
            The commit to diff against. Null for a non-pull-request event,
            leaving diff-derived signals without evidence.
          example: 1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d
        branch:
          type: string
          example: feature/widget-cache
        prNumber:
          type:
            - integer
            - 'null'
          description: Null for a non-pull-request event.
          example: 4213
        runId:
          type: string
          description: >-
            `BUILDKITE_BUILD_NUMBER`, recorded so the plan can later be scored
            against the build's outcome. Not `BUILDKITE_BUILD_ID`: a build Trunk
            started before queue is matched by its number.
          example: '4821'
        runAttempt:
          type: integer
          description: >-
            Which attempt this is, counting from 1. An agent's
            `BUILDKITE_RETRY_COUNT` counts from 0, so send it plus one.
          example: 1
        triggeringActor:
          type: string
          description: '`BUILDKITE_BUILD_CREATOR`.'
          example: octocat
        eventName:
          type: string
          description: What triggered the build — `BUILDKITE_SOURCE`.
          example: webhook
        prLabels:
          type: array
          items:
            type: string
            maxLength: 256
          maxItems: 1000
          deprecated: true
          description: >-
            Ignored. Trunk reads the pull request's labels itself when the run
            asks for a plan. While the repository is in Learning mode, a pull
            request carrying a label on the repository's managed allow list
            (matched case-insensitively) is gated as if Dynamic CI were enabled.
            Accepted so that older clients still validate.
          example:
            - bug
            - ready-for-ci
        jobKeys:
          type: array
          items:
            type: string
          maxItems: 1000
          default: []
          description: >-
            The step `key:` values to decide — what Trunk ingests from
            `buildkite.step.key`. **Empty means every keyed step in the
            pipeline** — the usual call.
          example:
            - unit-tests
        ignoreSignals:
          type: array
          items:
            $ref: '#/components/schemas/SignalType'
          maxItems: 64
          description: >-
            Signals to drop from the tally. An unrecognized identifier is
            rejected, so a typo surfaces.
          example:
            - estimated-cost
        changedFiles:
          $ref: '#/components/schemas/ChangedFiles'
        impacts:
          type: array
          items:
            $ref: '#/components/schemas/PlanImpact'
          maxItems: 8
          description: >-
            How much of the codebase the change affects, by each measure your
            own build or dependency tool computes, one entry per source. Jobs
            with the impact reach signal turned on always run a change that
            affects everything, lean toward running a broad change and lean
            slightly toward skipping a narrow one. Omit it when your tool
            computed nothing; sending nothing leaves every verdict as it is.
        buildkiteOrganizationSlug:
          type: string
          minLength: 1
          maxLength: 200
          description: '`BUILDKITE_ORGANIZATION_SLUG` on an agent.'
          example: acme
        buildkitePipelineSlug:
          type: string
          minLength: 1
          maxLength: 200
          description: '`BUILDKITE_PIPELINE_SLUG` on an agent.'
          example: widgets-pr
        matrixBlocks:
          type: object
          additionalProperties: {}
          description: >-
            Each keyed matrix step's `matrix:` block, by step key, as
            `buildkite-agent pipeline upload --dry-run` renders it with
            environment variables resolved. Matrix steps are pruned per
            variation only when their block is sent; a step left out is decided
            as a whole. Send at most 64 KiB of blocks; Trunk ignores a larger
            map.
          example:
            build-image:
              - amd64
              - arm64
        rbqDispatchId:
          type: string
          format: uuid
          description: >-
            Set by Trunk's Run Before Queue on a build it created
            (`TRUNK_RBQ_DISPATCH_ID`). Send it unchanged when the variable is
            present.
          example: 3f9d2c1e-7a4b-4e8f-9c2d-5b6a7e8f9a0b
      required:
        - repo
        - commitSha
        - baseSha
        - branch
        - prNumber
        - runId
        - runAttempt
        - buildkiteOrganizationSlug
        - buildkitePipelineSlug
    CiPlan:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobVerdict'
          maxItems: 1000
          description: >-
            One verdict per job. **A job absent from this list must be run** —
            the documented fail-safe, and how an unrecognized job, a CI job
            experiment branch, and a not-yet-enabled organization are all
            reported.
        notice:
          $ref: '#/components/schemas/PlanNotice'
      required:
        - jobs
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: >-
                Human-readable description of what went wrong. Not stable — do
                not parse.
              example: An unexpected error occurred
          required:
            - code
            - message
      required:
        - error
      description: >-
        The error envelope. Every error this API itself returns has this shape,
        except a `413` for a body over 512 KB and a `504` for a request that
        runs past its time limit, which are plain text. Responses from Trunk's
        edge, such as a `401`, a `403` for a missing credential, a `429` or a
        `503`, can arrive before the request reaches the API and may not have
        it, so read `error.code` only when the body is JSON with an `error`
        object.
    PlanRepo:
      type: object
      properties:
        host:
          type: string
          default: github.com
          description: >-
            Disambiguates GitHub.com from a GitHub Enterprise Server host.
            `github.com` is the only supported value today.
          example: github.com
        owner:
          type: string
          example: acme
        name:
          type: string
          example: widgets
      required:
        - owner
        - name
    SignalType:
      type: string
      enum:
        - estimated-cost
        - previous-result-on-pr
        - historical-pass-rate
        - diff-driven-volatility
        - force-override
        - merge-failure
        - mid-pr-stack
        - required-check
        - merge-queue-is-required
        - paths-filter
        - draft-pull-request
        - impact-reach
      description: >-
        Which independent signal produced a contribution to a job's verdict.
        These identifiers are also what `ignoreSignals` accepts.
      example: historical-pass-rate
    ChangedFiles:
      type: object
      properties:
        base:
          type: string
          minLength: 1
          maxLength: 4096
          description: The commit or ref the diff was taken from.
          example: 1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d
        totalFiles:
          type: integer
          minimum: 0
          description: How many files changed, before the 200-file cap.
          example: 1
        totalAdditions:
          type: integer
          minimum: 0
          description: Lines added across every changed file, before the cap.
          example: 12
        totalDeletions:
          type: integer
          minimum: 0
          description: Lines removed across every changed file, before the cap.
          example: 3
        files:
          type: array
          items:
            $ref: '#/components/schemas/ChangedFile'
          maxItems: 200
          description: >-
            The first 200 changed files. Must hold exactly `min(totalFiles,
            200)` entries.
      required:
        - base
        - totalFiles
        - totalAdditions
        - totalDeletions
        - files
      description: >-
        The files changed between `base` and `commitSha`, diffed from their
        merge base (`base...commitSha`). No file contents. **Omit it if you
        cannot compute the diff; never send an empty list in its place.** An
        empty list says nothing changed, which is the strongest evidence to
        skip. When it is absent, Trunk fetches the diff through your GitHub App
        installation.
    PlanImpact:
      type: object
      properties:
        source:
          type: string
          pattern: ^[a-z0-9][a-z0-9._-]{0,63}$
          description: >-
            The measure, such as `tainted-packages` or `test-files`: lowercase
            letters, digits, `.`, `_` and `-`, at most 64 characters. Trunk sets
            each job's maximum per source, so keep a source's name and measure
            the same on every request.
          example: tainted-packages
        count:
          type: integer
          minimum: 0
          maximum: 10000000
          description: >-
            How many units your build tool says the change affects: packages,
            targets, test files or tests. Required unless `all` is true, and
            ignored when it is. `0` means nothing is affected, not unknown.
          example: 734
        all:
          type: boolean
          default: false
          description: >-
            The tool says the change affects everything, or could not work out
            what is affected. Never send a large `count` in its place.
          example: false
      required:
        - source
    JobVerdict:
      type: object
      properties:
        jobKey:
          type: string
          description: >-
            The workflow's declarative `jobs:` key — what `github.job` reports
            and what an `if:` names.
          example: unit-tests
        run:
          type: boolean
          description: Whether this job should run.
          example: false
        summary:
          type: string
          description: One-line rationale for the verdict, safe to show to a user.
          example: 'Skipping: no changed file has ever broken this job.'
        signals:
          type: array
          items:
            $ref: '#/components/schemas/SignalResult'
          maxItems: 64
          description: The audit trail behind `summary`, abstentions included.
        variations:
          type: array
          items:
            $ref: '#/components/schemas/VariationVerdict'
          maxItems: 256
          description: >-
            One verdict per matrix variation, for a job decided per variation.
            Informational: act on `run` and `prune`, never on these.
        prune:
          $ref: '#/components/schemas/Prune'
      required:
        - jobKey
        - run
        - summary
        - signals
    PlanNotice:
      type: object
      properties:
        code:
          type: string
          description: >-
            A stable identifier for the condition, safe to branch on. Today:
            `ORG_NOT_ENABLED`, `REPO_NOT_ENABLED`, `REPO_IN_SHADOW_MODE`,
            `ENGINE_UNAVAILABLE`, `WORKFLOW_NOT_RECOGNIZED`, `EXPERIMENT_BRANCH`
            (a Trunk Runners experiment branch, where every job runs).
            `MERGE_QUEUE_BRANCH` is retired and no longer sent — merge-queue
            runs now carry real per-job verdicts. **An open set** — fall back to
            `message` for a code you do not recognize.
          example: ORG_NOT_ENABLED
        message:
          type: string
          description: The condition in prose, safe to show to a user verbatim.
          example: >-
            Every job will run: Dynamic CI is not enabled for this organization.
            Contact Trunk to turn it on.
      required:
        - code
        - message
      description: >-
        Why this plan has the shape it does. **Absent unless every job runs for
        a reason `jobs` cannot express**: a not-yet-enabled organization or
        repository, a CI job experiment branch (`trunk-runners/experiments/`),
        an engine outage, or a workflow Trunk has not enumerated — all
        indistinguishable otherwise, and all arriving as an empty `jobs` when
        you request a whole workflow. `REPO_IN_SHADOW_MODE` is the exception:
        the plan is fully populated and each `summary` is the recommendation the
        job would have received, but nothing is allowed to skip.
    ErrorCode:
      type: string
      enum:
        - AUTHENTICATION_REQUIRED
        - INVALID_TOKEN
        - INSUFFICIENT_PERMISSIONS
        - INTERNAL_ERROR
        - VALIDATION_FAILED
        - NOT_FOUND
        - INVALID_CURSOR
        - MERGE_QUEUE_NOT_FOUND
        - PR_ALREADY_ENQUEUED
        - PR_NOT_ENQUEUEABLE
        - UPSTREAM_ERROR
        - VERIFICATION_RUN_NOT_FOUND
        - PR_NOT_FOUND
        - IMPACTED_TARGETS_NOT_FOUND
        - REPOSITORY_NOT_FOUND
        - IMPACTED_TARGETS_UNSUPPORTED
        - QUEUE_ALREADY_EXISTS
        - QUEUE_HAS_ACTIVE_ENTRIES
        - MODE_CHANGE_IN_PROGRESS
        - PR_NOT_IN_ACTIVE_STATE
        - MERGE_QUEUE_NOT_CREATABLE
        - PR_TESTS_NOT_RESTARTABLE
        - ALLOWED_BOT_SUBMITTERS_FROZEN
        - ESTIMATE_NOT_ENABLED
        - PR_RERUN_FEATURE_DISABLED
        - PR_RERUN_NOT_PENDING_FAILURE
        - PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS
        - PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE
        - PR_RERUN_CHECK_NOT_RERUNNABLE
        - PR_RERUN_RUN_TORN_DOWN
        - PR_RERUN_HOLD_LIMIT_REACHED
        - PR_RERUN_FORGE_NOT_SUPPORTED
        - PROVIDER_URL_NOT_FOUND
        - CI_HOST_UNSUPPORTED
        - CI_JOB_NOT_FOUND
        - CI_FAILURE_CLUSTER_NOT_FOUND
        - TEST_COLLECTION_NOT_FOUND
        - TEST_NOT_FOUND
        - TEST_UPLOAD_NOT_FOUND
        - MONITOR_NOT_FOUND
        - MONITOR_LIMIT_EXCEEDED
        - MONITOR_NOT_ACTIVE
        - OUT_OF_RANGE
        - TEST_UNAVAILABLE
        - TICKETING_NOT_CONFIGURED
        - TICKETING_CREDENTIALS_INVALID
        - TICKETING_SITE_REFUSED
        - TICKET_NOT_FOUND
        - TICKET_NOT_LINKED
        - TICKET_LINK_CONFLICT
        - TEST_ALREADY_LINKED
        - TICKET_FIELDS_REJECTED
        - TICKET_CONTENT_UNAVAILABLE
        - TICKETING_CREATE_REFUSED
        - RATE_LIMIT_EXCEEDED
      description: >-
        Stable machine-readable error identifier. Switch on this, never on
        `message`. A shipped code's meaning never changes, but **new codes may
        be added within v2** — treat an unrecognized code as a generic failure
        of its HTTP status rather than failing closed.
      example: INTERNAL_ERROR
    ChangedFile:
      type: object
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
          example: src/cache.ts
        previousPath:
          type: string
          minLength: 1
          maxLength: 4096
          description: The old path, for a `renamed` or `copied` file.
          example: src/lru.ts
        status:
          $ref: '#/components/schemas/ChangedFileStatus'
        additions:
          type: integer
          minimum: 0
          description: Lines added. 0 for a binary file.
          example: 12
        deletions:
          type: integer
          minimum: 0
          description: Lines removed. 0 for a binary file.
          example: 3
      required:
        - path
        - status
        - additions
        - deletions
    SignalResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SignalType'
        recommendation:
          $ref: '#/components/schemas/SignalRecommendation'
        message:
          type: string
          description: Human-readable evidence for this signal's contribution.
          example: Reliably green (98.0% pass rate over 240 runs).
        ignored:
          type: boolean
          description: >-
            True when `ignoreSignals` excluded this signal from the tally. Its
            `recommendation` is what it would have contributed.
          example: false
      required:
        - type
        - recommendation
        - message
        - ignored
    VariationVerdict:
      type: object
      properties:
        match:
          type: object
          additionalProperties: {}
          description: >-
            The variation's matrix values, each as typed JSON. Informational: a
            number may lose how it was written (`3.10` reads as `3.1`), so never
            build a matrix output from it; set `prune` instead.
          example:
            os: macos-14
            node: 20
        group:
          type: object
          additionalProperties: {}
          description: >-
            The values of `match` on the job's variation dimensions: the
            decision group whose verdict this variation took, and what to label
            this variation by. Empty when the variation sets none of them.
            Variations in one group can still differ in `run`, because a
            variation that cannot be pruned runs while its group skips, so
            combine variations into one line only when both `group` and `run`
            match.
          example:
            os: macos-14
        run:
          type: boolean
          description: Whether this variation's legs should run.
          example: false
        summary:
          type: string
          description: >-
            One-line rationale for this variation's verdict, safe to show to a
            user.
          example: The job should skip because no changed file has ever broken it.
      required:
        - match
        - run
        - summary
    Prune:
      type: object
      properties:
        exclude:
          type: string
          description: >-
            Set as the `<job>-exclude` output, unchanged, for a matrix declared
            with axes and wired as `exclude: ${{ fromJSON(<output> || '[...your
            own excludes...]') }}`. A JSON array: your own `exclude` entries
            first, then one entry per pruned leg. Do not parse or re-encode it:
            GitHub matches `exclude` by JSON type.
          example: '[{"os":"macos-14","node":20}]'
        matrix:
          type: string
          description: >-
            Set as the `<job>-matrix` output, unchanged, for a matrix written as
            `matrix: ${{ fromJSON(<output> || '{"include":[...]}') }}`. A JSON
            object `{"include": [...]}` holding the rows that run, each exactly
            as written in your literal, so leg names do not change.
          example: '{"include":[{"lane":"parallel","shard":1}]}'
        include:
          type: string
          description: >-
            Set as the `<job>-include` output, unchanged, for a matrix wired as
            `include: ${{ fromJSON(<output> || '[...]') }}`. The same rows as
            `matrix`, as a bare JSON array.
          example: '[{"lane":"parallel","shard":1}]'
        dropSetup:
          type: array
          items:
            type: integer
            minimum: 0
          maxItems: 50
          description: >-
            For a Buildkite matrix with no dimension names (`matrix: [a, b]` or
            `setup: [a, b]`): the positions in the step's setup list to delete,
            counted from 0 in the list you sent in `matrixBlocks`, ascending.
            Delete them from the step you upload; never every position.
          example:
            - 1
        adjustments:
          type: array
          items:
            $ref: '#/components/schemas/PruneAdjustment'
          maxItems: 12
          description: >-
            For a Buildkite matrix with named dimensions: entries to append,
            unchanged, to the step's `matrix.adjustments`. Each skips one
            variation. With your own adjustments, the step never has more than
            Buildkite's limit of 12.
      description: >-
        Present only when some legs of this matrix job are skipped and others
        run. Each field is the exact text for one output; a client sets it
        unchanged. When every leg is skipped, `run` is false and `prune` is
        absent.
    ChangedFileStatus:
      type: string
      enum:
        - added
        - modified
        - removed
        - renamed
        - copied
        - changed
        - unchanged
      description: >-
        How the file changed. The values GitHub reports, so its `status` can be
        passed through. `changed` (a type change, such as a file becoming a
        symlink) is read as `modified`.
      example: modified
    SignalRecommendation:
      type: string
      enum:
        - MUST_RUN
        - VOTE_RUN
        - VOTE_NO_RUN
        - NEVER_RUN
        - INCOMPLETE
        - ABSTAIN
      description: >-
        One signal's contribution. `MUST_RUN` and `NEVER_RUN` are hard verdicts
        (a single one decides, with `MUST_RUN` winning a tie); `VOTE_RUN` and
        `VOTE_NO_RUN` are weighted votes. `INCOMPLETE` means the signal applies
        but lacks evidence — two of them fail the job safe to running. `ABSTAIN`
        means the signal does not apply at all and is excluded from the tally
        entirely, which is what makes it different from `INCOMPLETE`.
      example: VOTE_NO_RUN
    PruneAdjustment:
      type: object
      properties:
        with:
          type: object
          additionalProperties:
            type: string
          description: >-
            The variation's value for each named dimension, as strings.
            Buildkite matches these against your `setup` values by their string
            form.
          example:
            os: macos
            arch: arm64
        skip:
          type: string
          description: >-
            The reason Buildkite shows for the skipped variation. It starts with
            `Trunk Dynamic CI:`.
          example: 'Trunk Dynamic CI: no changed file has broken this variation.'
      required:
        - with
        - skip
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key, sent as `Authorization: Bearer <key>`. An organization admin
        creates one in the Trunk app under **Settings → Developer → API Keys**
        and chooses the permissions it holds. A key with none can read merge
        queues but change nothing in them. Permissions cover merge queues and
        test-result uploads, including the quarantine lookups a CI run makes
        before it uploads; any key can call the other Flaky Tests and Dynamic CI
        endpoints, including their writes.
    trunkToken:
      type: apiKey
      in: header
      name: x-trunk-token
      description: >-
        A short-lived token that Trunk's own tools send in the `x-trunk-token`
        header: the `trunk` CLI after `trunk auth login`, and the
        `trunk-io/login` action in a GitHub Actions run. Your own integrations
        should use an API key instead. Never send `Authorization` and
        `x-trunk-token` on the same request.


        **A token from a GitHub Actions run can only upload and read impacted
        targets** (`PUT /v2/impacted-targets` and `GET
        /v2/pull-requests/{id}/impacted-targets`), for the repository the run
        belongs to. On a pull request from a fork it can also call the Flaky
        Tests CLI endpoints. Every other endpoint refuses it.

````