diff --git a/changelog/2026-08-26-browser-extension-1-0.mdx b/changelog/2026-08-26-browser-extension-1-0.mdx index 2ebe9c09..55a1bf27 100644 --- a/changelog/2026-08-26-browser-extension-1-0.mdx +++ b/changelog/2026-08-26-browser-extension-1-0.mdx @@ -1,8 +1,8 @@ --- -title: "Browser Extension 1.0.0 : Out of beta" +title: "Browser Extension 1.0: Out of beta" description: "The Trunk browser extension graduates from beta with more reliable queue controls, clearer failure details, and groundwork for expanding Merge Queue beyond GitHub." slug: "browser-extension-1-0" -date: "2026-08-26T00:00:00.000Z" +date: "2026-08-26" category: "Merge Queue" type: "update" --- diff --git a/docs.json b/docs.json index 941e49ef..3155f0a1 100644 --- a/docs.json +++ b/docs.json @@ -118,10 +118,13 @@ "pages": [ "POST /cancelPullRequest", "POST /getSubmittedPullRequest", + "POST /getSubmittedPullRequests", + "POST /listPullRequests", "POST /restartTestsOnPullRequest", "POST /setImpactedTargets", "POST /submitPullRequest", - "POST /getMergeQueueTestingDetails" + "POST /getMergeQueueTestingDetails", + "POST /listMergeQueueTestingResults" ] }, { diff --git a/merge-queue/reference/merge.mdx b/merge-queue/reference/merge.mdx index d8bb63ad..73ec9687 100644 --- a/merge-queue/reference/merge.mdx +++ b/merge-queue/reference/merge.mdx @@ -17,8 +17,11 @@ All requests must be [authenticated](../../setup-and-administration/apis/#authen | [`/cancelPullRequest`](/merge-queue/reference/merge/cancel-a-pull-request-in-a-merge-queue) | POST | Remove a PR from the merge queue | | [`/restartTestsOnPullRequest`](/merge-queue/reference/merge/restart-tests-on-a-pull-request-in-a-merge-queue) | POST | Re-run tests on a PR currently in the queue | | [`/getSubmittedPullRequest`](/merge-queue/reference/merge/get-a-submitted-pull-request-from-a-merge-queue) | POST | Check the status of a submitted PR | +| [`/getSubmittedPullRequests`](/merge-queue/reference/merge/get-several-submitted-pull-requests-from-a-merge-queue) | POST | Check the status of many submitted PRs at once | +| [`/listPullRequests`](/merge-queue/reference/merge/list-pull-requests-in-a-merge-queue) | POST | List the PRs in a queue, filtered by state or concluded time range | | [`/setImpactedTargets`](/merge-queue/reference/merge/set-impacted-targets-for-a-pull-request) | POST | Set impacted targets for a PR (used with [parallel queues](../optimizations/parallel-queues/)) | | [`/getMergeQueueTestingDetails`](/merge-queue/reference/merge/get-details-about-testing-that-merge-queue-is-performing) | POST | Get details about in-progress merge queue testing | +| [`/listMergeQueueTestingResults`](/merge-queue/reference/merge/list-completed-merge-queue-testing-for-a-time-range) | POST | List completed merge queue testing over a time range | | [`/createQueue`](/merge-queue/reference/merge/create-a-new-merge-queue) | POST | Create a new merge queue for a branch | | [`/deleteQueue`](/merge-queue/reference/merge/delete-the-specified-merge-queue-the-queue-must-be-empty-in-order-to-be-deleted) | POST | Delete an empty merge queue | | [`/getQueue`](/merge-queue/reference/merge/get-the-merge-queue) | POST | Get queue state, configuration, and enqueued PRs | @@ -156,12 +159,22 @@ The response includes the queue state (`RUNNING`, `PAUSED`, `DRAINING`, or `SWIT + + + +Three endpoints read pull request state, and which one you want depends on whether you already know +the pull requests you care about: + +* [`/getSubmittedPullRequest`](/merge-queue/reference/merge/get-a-submitted-pull-request-from-a-merge-queue) — one known PR, identified by number or head branch. +* [`/getSubmittedPullRequests`](/merge-queue/reference/merge/get-several-submitted-pull-requests-from-a-merge-queue) — up to 50 known PRs in one request, with the same full record each: readiness, whether the PR is currently submitted, and optionally the timeline of every state change. +* [`/listPullRequests`](/merge-queue/reference/merge/list-pull-requests-in-a-merge-queue) — discovery, when you don't know which PRs to ask about. Pages through the queue with a cursor and filters by state or by when PRs concluded, returning a summary row per PR rather than the full record. + Large monorepos can produce target lists that exceed the 20 MiB request body limit. If you hit this limit, send `"ALL"` as the `impactedTargets` value to mark the PR as impacting every target. diff --git a/openapi.json b/openapi.json index 75c71034..c1a13509 100644 --- a/openapi.json +++ b/openapi.json @@ -391,11 +391,12 @@ "name" ] }, + "targetBranch": { + "type": "string" + }, "pr": { - "description": "The pull request to look up. Identify it by number or by head branch, but not both.", "oneOf": [ { - "title": "By pull request number", "type": "object", "properties": { "number": { @@ -407,31 +408,35 @@ }, "required": [ "number" - ] + ], + "title": "By pull request number" }, { - "title": "By head branch", "type": "object", "properties": { "branch": { "type": "string", + "minLength": 1, "description": "The head branch of the pull request. Because a branch name can be reused by many pull requests over time (for example, bots that repeatedly open and merge pull requests from the same branch), the branch is resolved to a single pull request: the open pull request submitted to the merge queue from this branch if one exists, otherwise the most recently closed pull request submitted from this branch, otherwise `404`. Only pull requests that have been submitted to the merge queue are considered." } }, "required": [ "branch" - ] + ], + "title": "By head branch" } - ] + ], + "description": "The pull request to look up. Identify it by number or by head branch, but not both." }, - "targetBranch": { - "type": "string" + "includeTimeline": { + "type": "boolean", + "description": "When true, the response carries `timeline`: every state change the pull request went through, with timestamps and the details of each. Defaults to false." } }, "required": [ "repo", - "pr", - "targetBranch" + "targetBranch", + "pr" ] } } @@ -446,7 +451,8 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "This queue entry's ID. It identifies the entry, not the pull request — a pull request resubmitted after a cancellation gets a new one." }, "state": { "type": "string", @@ -495,6 +501,635 @@ ], "description": "Readiness signals for a pull request in the merge queue. A PR can start testing when `doesBaseBranchMatch` is true, `gitHubMergeability` is `mergeable`, and (when `requiresImpactedTargets` is true) `hasImpactedTargets` is true." }, + "timeline": { + "type": "array", + "items": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The state the pull request entered at this point." + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "When the pull request entered `state`, as an RFC 3339 timestamp in UTC." + }, + "testRun": { + "type": "object", + "properties": { + "testRunId": { + "type": "string", + "description": "The ID of the test run. Pass it to `getMergeQueueTestingDetails` for the full check-run breakdown." + }, + "testBranch": { + "type": "string" + }, + "testBranchSha": { + "type": "string" + }, + "prNumber": { + "type": "number", + "description": "The number of the pull request the queue opened for this test run." + }, + "prUrl": { + "type": "string", + "description": "The URL of the test run's pull request — where its checks and logs are." + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "When the test run started, as an RFC 3339 timestamp in UTC." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "failed", + "cancelled", + "succeeded" + ], + "description": "The outcome of the test run itself, independent of this pull request's state." + }, + "requiredStatuses": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The checks the test run had to pass for the pull requests in it to merge." + }, + "requiredStatusesSource": { + "type": "string", + "enum": [ + "trunk_config", + "repo_provider_branch_protection", + "merge_instance" + ], + "description": "Where `requiredStatuses` came from." + }, + "testedPullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "Every pull request tested together in this run, including this one." + } + }, + "required": [ + "testBranch", + "testBranchSha", + "requiredStatuses", + "testedPullRequests" + ], + "description": "The merge queue test run this timeline entry refers to." + }, + "notReady": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "user_requested", + "trunk_admin_requested", + "api_requested" + ], + "description": "How the pull request came to be submitted. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + }, + "priorityValue": { + "type": "number" + }, + "priorityName": { + "type": "string" + }, + "noBatch": { + "type": "boolean" + } + }, + "description": "Present on `not_ready` entries: the pull request was submitted to the queue." + }, + "pending": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "manual_push_to_target_branch", + "prerequisite_merge_item_cancelled", + "prerequisite_merge_item_failed", + "prerequisite_merge_item_manually_merged", + "merge_item_now_ready", + "tests_restarted_by_user", + "tests_restarted_by_api_request", + "skip_the_line_interrupted", + "bisection_required", + "bisection_test_run_passed" + ], + "description": "Why the pull request is queued rather than testing. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + }, + "priorityValue": { + "type": "number" + }, + "priorityName": { + "type": "string" + }, + "usedDefaultPriorityName": { + "type": "string" + }, + "prerequisitePullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "The pull requests ahead of this one that it is queued behind." + } + }, + "required": [ + "prerequisitePullRequests" + ], + "description": "Present on `pending` entries: the pull request is queued, waiting to be tested." + }, + "testsPassed": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "test_run_passed", + "successor_test_run_passed", + "passed_by_optimization" + ], + "description": "How the pull request came to pass. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "testRunId": { + "type": "string" + }, + "testBranchSha": { + "type": "string" + }, + "testBranchUrl": { + "type": "string" + }, + "batchSize": { + "type": "number" + }, + "bisectionId": { + "type": "string" + }, + "successorMergeItemId": { + "type": "string", + "description": "The queue entry behind this one whose test run vouched for it, as an `id` — look it up among the `id` fields returned by `getSubmittedPullRequests`. Set when `reason` is `successor_test_run_passed`." + }, + "otherTestedPullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + } + }, + "waitingFor": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "Pull requests ahead of this one that must merge before it can." + } + }, + "required": [ + "testBranchSha", + "testBranchUrl", + "batchSize", + "otherTestedPullRequests", + "waitingFor" + ] + }, + "pendingFailure": { + "type": "object", + "properties": { + "eventualFailureReason": { + "type": "string", + "enum": [ + "start_test_run_invalid_event", + "start_test_run_merge_conflict", + "start_test_run_config_not_found", + "start_test_run_config_parsing_failure", + "start_test_run_config_missing_required_statuses", + "start_test_run_config_bad_required_statuses", + "start_test_run_config_bad_version", + "start_test_run_no_required_statuses", + "start_test_run_retry_exhausted", + "start_test_run_draft_prs_not_allowed", + "start_test_run_permissions_block_test_branch", + "test_run_required_status_failed", + "test_run_timeout", + "test_run_failed_by_optimization", + "github_api_merge_pr_failed", + "github_api_direct_merge_pr_failed", + "github_api_rate_limit_exceeded", + "github_api_branch_protection_unmet", + "github_api_merge_already_in_progress", + "github_api_repeated_server_errors", + "pr_updated_at_merge_time" + ], + "description": "Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "waitingFor": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + } + }, + "failureCausingStatuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the check, as it appears on the pull request." + }, + "url": { + "type": "string", + "description": "A link to the failing check, when one was recorded." + }, + "conclusion": { + "type": "string", + "description": "Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured." + } + }, + "required": [ + "name" + ] + } + } + }, + "required": [ + "waitingFor", + "failureCausingStatuses" + ], + "description": "Present on `pending_failure` entries: this pull request will fail, but the queue is waiting on the pull requests ahead of it to establish the blame." + }, + "failure": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "start_test_run_invalid_event", + "start_test_run_merge_conflict", + "start_test_run_config_not_found", + "start_test_run_config_parsing_failure", + "start_test_run_config_missing_required_statuses", + "start_test_run_config_bad_required_statuses", + "start_test_run_config_bad_version", + "start_test_run_no_required_statuses", + "start_test_run_retry_exhausted", + "start_test_run_draft_prs_not_allowed", + "start_test_run_permissions_block_test_branch", + "test_run_required_status_failed", + "test_run_timeout", + "test_run_failed_by_optimization", + "github_api_merge_pr_failed", + "github_api_direct_merge_pr_failed", + "github_api_rate_limit_exceeded", + "github_api_branch_protection_unmet", + "github_api_merge_already_in_progress", + "github_api_repeated_server_errors", + "pr_updated_at_merge_time" + ], + "description": "Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "apiFailureMessage": { + "type": "string" + }, + "failureCausingStatuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the check, as it appears on the pull request." + }, + "url": { + "type": "string", + "description": "A link to the failing check, when one was recorded." + }, + "conclusion": { + "type": "string", + "description": "Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured." + } + }, + "required": [ + "name" + ] + }, + "description": "The required checks that failed. Populated when `reason` is `test_run_required_status_failed`." + }, + "blockReasons": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "Which requirement was unmet: `review_required`, `changes_requested`, `failing_required_check`, `awaiting_required_check`, `behind_base`, `merge_conflict`, `stack_needs_rebase`, or `undetermined`. The fields below are populated per kind. New kinds may be added." + }, + "have": { + "type": "number", + "description": "Approvals received, for `review_required`." + }, + "need": { + "type": "number", + "description": "Approvals required, for `review_required`." + }, + "check": { + "type": "string", + "description": "The check's name, for the `*_required_check` kinds." + }, + "status": { + "type": "string", + "description": "The check's status, when it has one." + }, + "state": { + "type": "string", + "description": "The check's state, when it has one." + }, + "ontoPrNumber": { + "type": "number", + "description": "For `stack_needs_rebase`, the pull request this one's branch must be rebased onto." + } + }, + "required": [ + "kind" + ] + }, + "description": "The unmet branch-protection requirements. Populated when `reason` is `github_api_branch_protection_unmet`." + }, + "conflictCulprit": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "sha": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "queue_pr", + "base_branch", + "stacked_pr" + ] + } + }, + "required": [ + "type" + ], + "description": "The earlier queue entry a merge conflict was traced to. Identified asynchronously, so it is absent until the investigation finishes, and permanently absent when no single entry was to blame." + } + }, + "required": [ + "failureCausingStatuses", + "blockReasons" + ] + }, + "cancellation": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "user_requested", + "trunk_admin_requested", + "pr_closed", + "pr_pushed_to", + "pr_base_branch_changed", + "pr_converted_to_draft", + "not_ready_timeout_expired", + "stacked_pr_member_pushed_to", + "stacked_pr_member_closed", + "stacked_pr_member_merged", + "stacked_pr_member_base_branch_changed", + "stacked_pr_stack_changed", + "stacked_pr_group_cancelled_at_merge_time" + ], + "description": "Why the pull request was removed from the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + } + } + }, + "merged": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "merge_graph_merge", + "merge_graph_direct_merge", + "manual_merge" + ], + "description": "How the pull request was merged. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + } + } + } + }, + "description": "One state change in a pull request's life in the merge queue, with the details of why it happened. At most one of the per-state detail objects is present, matching `state`. `testRun` is independent of those and accompanies any entry that refers to a test run — a `testing` entry, and a `failed` or `pending_failure` entry whose cause was a test." + }, + "description": "Present only when the request set `includeTimeline`." + }, "stateChangedAt": { "type": "string" }, @@ -530,20 +1165,991 @@ }, "prAuthor": { "type": "string" + }, + "verifiedByTestRun": { + "type": [ + "object", + "null" + ], + "properties": { + "testRunId": { + "type": "string", + "description": "The ID of the test run that caused this pull request to be merged." + }, + "testBranchSha": { + "type": "string", + "description": "The commit SHA of the head of the test branch for this test run." + } + }, + "required": [ + "testRunId", + "testBranchSha" + ], + "description": "The merge queue test run that verified this pull request before it was merged. For an optimistically merged pull request, this is the test run of the pull request behind it whose passing caused the optimistic merge. Null if the pull request is not merged, or was merged without a verifying test run (e.g. force merged)." + } + }, + "required": [ + "stateChangedAt", + "priorityValue", + "priorityName", + "skipTheLine", + "forceEnqueued", + "isCurrentlySubmittedToQueue", + "prNumber", + "prTitle", + "prSha", + "prBaseBranch", + "prAuthor", + "verifiedByTestRun" + ] + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/getSubmittedPullRequests": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "summary": "Get several submitted pull requests from a merge queue.", + "description": "The batch form of `getSubmittedPullRequest`, for building a view over many pull requests at once. Every pull request must be in the same repository and queue. Pull requests that were never submitted to the queue are reported in `notFound` rather than failing the request.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "repo": { + "type": "object", + "properties": { + "host": { + "type": "string" + }, + "owner": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "host", + "owner", + "name" + ] + }, + "targetBranch": { + "type": "string" + }, + "prs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "number": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "The pull request number." + } + }, + "required": [ + "number" + ], + "title": "By pull request number" + }, + { + "type": "object", + "properties": { + "branch": { + "type": "string", + "minLength": 1, + "description": "The head branch of the pull request. Because a branch name can be reused by many pull requests over time (for example, bots that repeatedly open and merge pull requests from the same branch), the branch is resolved to a single pull request: the open pull request submitted to the merge queue from this branch if one exists, otherwise the most recently closed pull request submitted from this branch, otherwise `404`. Only pull requests that have been submitted to the merge queue are considered." + } + }, + "required": [ + "branch" + ], + "title": "By head branch" + } + ], + "description": "The pull request to look up. Identify it by number or by head branch, but not both." + }, + "minItems": 1, + "maxItems": 50, + "description": "The pull requests to look up, at most 50 per request. Each is identified the same way as in `getSubmittedPullRequest`." + }, + "includeTimeline": { + "type": "boolean", + "description": "When true, the response carries `timeline`: every state change the pull request went through, with timestamps and the details of each. Defaults to false." + } + }, + "required": [ + "repo", + "targetBranch", + "prs" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "This queue entry's ID. It identifies the entry, not the pull request — a pull request resubmitted after a cancellation gets a new one." + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The state of a pull request in the merge queue. See https://docs.trunk.io/merge-queue/using-the-queue/reference#pull-request-states for the full description of each state." + }, + "readiness": { + "type": "object", + "properties": { + "hasImpactedTargets": { + "type": "boolean", + "description": "Whether the set of impacted build/test targets for this PR has been reported." + }, + "requiresImpactedTargets": { + "type": "boolean", + "description": "Whether the queue is configured to require impacted-target reporting before a PR can start testing." + }, + "doesBaseBranchMatch": { + "type": "boolean", + "description": "Whether the PR's base branch matches the queue's target branch." + }, + "gitHubMergeability": { + "type": "string", + "enum": [ + "unspecified", + "in_progress", + "mergeable", + "not_mergeable" + ], + "description": "GitHub's mergeability state for the PR (cached). `unspecified` — not yet known. `in_progress` — GitHub is still computing mergeability. `mergeable` — GitHub reports the PR can be merged. `not_mergeable` — GitHub reports the PR cannot be merged (e.g. merge conflict)." + } + }, + "required": [ + "requiresImpactedTargets", + "doesBaseBranchMatch", + "gitHubMergeability" + ], + "description": "Readiness signals for a pull request in the merge queue. A PR can start testing when `doesBaseBranchMatch` is true, `gitHubMergeability` is `mergeable`, and (when `requiresImpactedTargets` is true) `hasImpactedTargets` is true." + }, + "timeline": { + "type": "array", + "items": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The state the pull request entered at this point." + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "When the pull request entered `state`, as an RFC 3339 timestamp in UTC." + }, + "testRun": { + "type": "object", + "properties": { + "testRunId": { + "type": "string", + "description": "The ID of the test run. Pass it to `getMergeQueueTestingDetails` for the full check-run breakdown." + }, + "testBranch": { + "type": "string" + }, + "testBranchSha": { + "type": "string" + }, + "prNumber": { + "type": "number", + "description": "The number of the pull request the queue opened for this test run." + }, + "prUrl": { + "type": "string", + "description": "The URL of the test run's pull request — where its checks and logs are." + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "When the test run started, as an RFC 3339 timestamp in UTC." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "failed", + "cancelled", + "succeeded" + ], + "description": "The outcome of the test run itself, independent of this pull request's state." + }, + "requiredStatuses": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The checks the test run had to pass for the pull requests in it to merge." + }, + "requiredStatusesSource": { + "type": "string", + "enum": [ + "trunk_config", + "repo_provider_branch_protection", + "merge_instance" + ], + "description": "Where `requiredStatuses` came from." + }, + "testedPullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "Every pull request tested together in this run, including this one." + } + }, + "required": [ + "testBranch", + "testBranchSha", + "requiredStatuses", + "testedPullRequests" + ], + "description": "The merge queue test run this timeline entry refers to." + }, + "notReady": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "user_requested", + "trunk_admin_requested", + "api_requested" + ], + "description": "How the pull request came to be submitted. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + }, + "priorityValue": { + "type": "number" + }, + "priorityName": { + "type": "string" + }, + "noBatch": { + "type": "boolean" + } + }, + "description": "Present on `not_ready` entries: the pull request was submitted to the queue." + }, + "pending": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "manual_push_to_target_branch", + "prerequisite_merge_item_cancelled", + "prerequisite_merge_item_failed", + "prerequisite_merge_item_manually_merged", + "merge_item_now_ready", + "tests_restarted_by_user", + "tests_restarted_by_api_request", + "skip_the_line_interrupted", + "bisection_required", + "bisection_test_run_passed" + ], + "description": "Why the pull request is queued rather than testing. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + }, + "priorityValue": { + "type": "number" + }, + "priorityName": { + "type": "string" + }, + "usedDefaultPriorityName": { + "type": "string" + }, + "prerequisitePullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "The pull requests ahead of this one that it is queued behind." + } + }, + "required": [ + "prerequisitePullRequests" + ], + "description": "Present on `pending` entries: the pull request is queued, waiting to be tested." + }, + "testsPassed": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "test_run_passed", + "successor_test_run_passed", + "passed_by_optimization" + ], + "description": "How the pull request came to pass. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "testRunId": { + "type": "string" + }, + "testBranchSha": { + "type": "string" + }, + "testBranchUrl": { + "type": "string" + }, + "batchSize": { + "type": "number" + }, + "bisectionId": { + "type": "string" + }, + "successorMergeItemId": { + "type": "string", + "description": "The queue entry behind this one whose test run vouched for it, as an `id` — look it up among the `id` fields returned by `getSubmittedPullRequests`. Set when `reason` is `successor_test_run_passed`." + }, + "otherTestedPullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + } + }, + "waitingFor": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + }, + "description": "Pull requests ahead of this one that must merge before it can." + } + }, + "required": [ + "testBranchSha", + "testBranchUrl", + "batchSize", + "otherTestedPullRequests", + "waitingFor" + ] + }, + "pendingFailure": { + "type": "object", + "properties": { + "eventualFailureReason": { + "type": "string", + "enum": [ + "start_test_run_invalid_event", + "start_test_run_merge_conflict", + "start_test_run_config_not_found", + "start_test_run_config_parsing_failure", + "start_test_run_config_missing_required_statuses", + "start_test_run_config_bad_required_statuses", + "start_test_run_config_bad_version", + "start_test_run_no_required_statuses", + "start_test_run_retry_exhausted", + "start_test_run_draft_prs_not_allowed", + "start_test_run_permissions_block_test_branch", + "test_run_required_status_failed", + "test_run_timeout", + "test_run_failed_by_optimization", + "github_api_merge_pr_failed", + "github_api_direct_merge_pr_failed", + "github_api_rate_limit_exceeded", + "github_api_branch_protection_unmet", + "github_api_merge_already_in_progress", + "github_api_repeated_server_errors", + "pr_updated_at_merge_time" + ], + "description": "Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "waitingFor": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "title": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "not_ready", + "pending", + "testing", + "tests_passed", + "merged", + "failed", + "cancelled", + "pending_failure" + ], + "description": "The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one." + } + } + } + }, + "failureCausingStatuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the check, as it appears on the pull request." + }, + "url": { + "type": "string", + "description": "A link to the failing check, when one was recorded." + }, + "conclusion": { + "type": "string", + "description": "Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured." + } + }, + "required": [ + "name" + ] + } + } + }, + "required": [ + "waitingFor", + "failureCausingStatuses" + ], + "description": "Present on `pending_failure` entries: this pull request will fail, but the queue is waiting on the pull requests ahead of it to establish the blame." + }, + "failure": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "start_test_run_invalid_event", + "start_test_run_merge_conflict", + "start_test_run_config_not_found", + "start_test_run_config_parsing_failure", + "start_test_run_config_missing_required_statuses", + "start_test_run_config_bad_required_statuses", + "start_test_run_config_bad_version", + "start_test_run_no_required_statuses", + "start_test_run_retry_exhausted", + "start_test_run_draft_prs_not_allowed", + "start_test_run_permissions_block_test_branch", + "test_run_required_status_failed", + "test_run_timeout", + "test_run_failed_by_optimization", + "github_api_merge_pr_failed", + "github_api_direct_merge_pr_failed", + "github_api_rate_limit_exceeded", + "github_api_branch_protection_unmet", + "github_api_merge_already_in_progress", + "github_api_repeated_server_errors", + "pr_updated_at_merge_time" + ], + "description": "Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "apiFailureMessage": { + "type": "string" + }, + "failureCausingStatuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the check, as it appears on the pull request." + }, + "url": { + "type": "string", + "description": "A link to the failing check, when one was recorded." + }, + "conclusion": { + "type": "string", + "description": "Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured." + } + }, + "required": [ + "name" + ] + }, + "description": "The required checks that failed. Populated when `reason` is `test_run_required_status_failed`." + }, + "blockReasons": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "Which requirement was unmet: `review_required`, `changes_requested`, `failing_required_check`, `awaiting_required_check`, `behind_base`, `merge_conflict`, `stack_needs_rebase`, or `undetermined`. The fields below are populated per kind. New kinds may be added." + }, + "have": { + "type": "number", + "description": "Approvals received, for `review_required`." + }, + "need": { + "type": "number", + "description": "Approvals required, for `review_required`." + }, + "check": { + "type": "string", + "description": "The check's name, for the `*_required_check` kinds." + }, + "status": { + "type": "string", + "description": "The check's status, when it has one." + }, + "state": { + "type": "string", + "description": "The check's state, when it has one." + }, + "ontoPrNumber": { + "type": "number", + "description": "For `stack_needs_rebase`, the pull request this one's branch must be rebased onto." + } + }, + "required": [ + "kind" + ] + }, + "description": "The unmet branch-protection requirements. Populated when `reason` is `github_api_branch_protection_unmet`." + }, + "conflictCulprit": { + "type": "object", + "properties": { + "prNumber": { + "type": "number" + }, + "prUrl": { + "type": "string" + }, + "sha": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "queue_pr", + "base_branch", + "stacked_pr" + ] + } + }, + "required": [ + "type" + ], + "description": "The earlier queue entry a merge conflict was traced to. Identified asynchronously, so it is absent until the investigation finishes, and permanently absent when no single entry was to blame." + } + }, + "required": [ + "failureCausingStatuses", + "blockReasons" + ] + }, + "cancellation": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "user_requested", + "trunk_admin_requested", + "pr_closed", + "pr_pushed_to", + "pr_base_branch_changed", + "pr_converted_to_draft", + "not_ready_timeout_expired", + "stacked_pr_member_pushed_to", + "stacked_pr_member_closed", + "stacked_pr_member_merged", + "stacked_pr_member_base_branch_changed", + "stacked_pr_stack_changed", + "stacked_pr_group_cancelled_at_merge_time" + ], + "description": "Why the pull request was removed from the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + } + } + }, + "merged": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "merge_graph_merge", + "merge_graph_direct_merge", + "manual_merge" + ], + "description": "How the pull request was merged. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing." + }, + "actor": { + "type": "object", + "properties": { + "gitHubLogin": { + "type": "string", + "description": "The GitHub login (not the display name) of the person who caused the change." + }, + "trunkUserId": { + "type": "string", + "description": "The Trunk user ID of the person who caused the change, when they have one." + } + }, + "description": "Who caused this state change. Absent when the queue itself caused it rather than a person." + } + } + } + }, + "description": "One state change in a pull request's life in the merge queue, with the details of why it happened. At most one of the per-state detail objects is present, matching `state`. `testRun` is independent of those and accompanies any entry that refers to a test run — a `testing` entry, and a `failed` or `pending_failure` entry whose cause was a test." + }, + "description": "Present only when the request set `includeTimeline`." + }, + "stateChangedAt": { + "type": "string" + }, + "priorityValue": { + "type": "number" + }, + "priorityName": { + "type": "string" + }, + "usedDefaultPriorityName": { + "type": "string" + }, + "skipTheLine": { + "type": "boolean" + }, + "forceEnqueued": { + "type": "boolean" + }, + "isCurrentlySubmittedToQueue": { + "type": "boolean" + }, + "prNumber": { + "type": "number" + }, + "prTitle": { + "type": "string" + }, + "prSha": { + "type": "string" + }, + "prBaseBranch": { + "type": "string" + }, + "prAuthor": { + "type": "string" + }, + "verifiedByTestRun": { + "type": [ + "object", + "null" + ], + "properties": { + "testRunId": { + "type": "string", + "description": "The ID of the test run that caused this pull request to be merged." + }, + "testBranchSha": { + "type": "string", + "description": "The commit SHA of the head of the test branch for this test run." + } + }, + "required": [ + "testRunId", + "testBranchSha" + ], + "description": "The merge queue test run that verified this pull request before it was merged. For an optimistically merged pull request, this is the test run of the pull request behind it whose passing caused the optimistic merge. Null if the pull request is not merged, or was merged without a verifying test run (e.g. force merged)." + } + }, + "required": [ + "stateChangedAt", + "priorityValue", + "priorityName", + "skipTheLine", + "forceEnqueued", + "isCurrentlySubmittedToQueue", + "prNumber", + "prTitle", + "prSha", + "prBaseBranch", + "prAuthor", + "verifiedByTestRun" + ] + }, + "description": "One entry per requested pull request that has been submitted to this queue, in the order requested. Pull requests that were not found are omitted here and listed in `notFound` instead, so this array can be shorter than `prs`. To line entries up with what you asked for, drop the `prs` entries echoed in `notFound`; what remains corresponds to this array position for position. Entries requested by number can also be matched on `prNumber`." + }, + "notFound": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "number": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "The pull request number." + } + }, + "required": [ + "number" + ], + "title": "By pull request number" + }, + { + "type": "object", + "properties": { + "branch": { + "type": "string", + "minLength": 1, + "description": "The head branch of the pull request. Because a branch name can be reused by many pull requests over time (for example, bots that repeatedly open and merge pull requests from the same branch), the branch is resolved to a single pull request: the open pull request submitted to the merge queue from this branch if one exists, otherwise the most recently closed pull request submitted from this branch, otherwise `404`. Only pull requests that have been submitted to the merge queue are considered." + } + }, + "required": [ + "branch" + ], + "title": "By head branch" + } + ], + "description": "The pull request to look up. Identify it by number or by head branch, but not both." + }, + "description": "The requested pull requests that have never been submitted to this queue, echoed back one per entry of `prs` that missed. A whole request fails only when the repository or queue itself is not found." } }, "required": [ - "stateChangedAt", - "priorityValue", - "priorityName", - "skipTheLine", - "forceEnqueued", - "isCurrentlySubmittedToQueue", - "prNumber", - "prTitle", - "prSha", - "prBaseBranch", - "prAuthor" + "pullRequests", + "notFound" ] } } @@ -662,11 +2268,19 @@ "since": { "type": "string", "format": "date-time", - "description": "Optional ISO 8601 timestamp. When provided, returns pull requests that concluded (merged, failed, or cancelled) since this time.", + "description": "Optional ISO 8601 timestamp. When provided, returns pull requests that concluded (merged, failed, or cancelled) since this time. Defaults to the beginning of time when only `until` is provided.", "examples": [ "2024-01-01T00:00:00Z" ] }, + "until": { + "type": "string", + "format": "date-time", + "description": "Optional ISO 8601 timestamp bounding the upper end of the concluded time range. When either `since` or `until` is provided, only pull requests that concluded (merged, failed, or cancelled) within the range are returned. Defaults to now.", + "examples": [ + "2024-02-01T00:00:00Z" + ] + }, "cursor": { "type": "string", "format": "uuid", @@ -929,6 +2543,10 @@ "statusCheckEnabled": { "type": "boolean" }, + "extensionEnabled": { + "type": "boolean", + "description": "Whether the Trunk Merge Queue browser extension is enabled (shown) for this repository." + }, "bisectionConcurrency": { "type": "number" }, @@ -938,6 +2556,39 @@ "type": "string" } }, + "allowedBotSubmitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The GitHub logins of bot/app accounts (e.g. `dependabot[bot]`) whose PRs are allowed to be submitted to the merge queue." + }, + "batchingRules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "targetPattern": { + "type": "string", + "minLength": 1, + "description": "The impacted-target label this rule applies to. Matched exactly, or as a prefix when it ends in a single `*` (e.g. `//db/migrations:*`). A `*` anywhere other than the last character is rejected, and `*` on its own is rejected — a rule matching every target is a queue-wide setting rather than a rule." + }, + "policy": { + "type": "string", + "enum": [ + "isolate" + ], + "description": "What to do with a PR whose impacted targets match. `isolate` tests it on its own, exactly as `/trunk merge --no-batch` does." + } + }, + "required": [ + "targetPattern", + "policy" + ], + "description": "A rule that changes how a PR is batched based on the build targets it impacts. Evaluated from the impacted targets uploaded for the PR's head commit each time the queue forms batches, so it follows pushes that add or remove a matching target. A PR that reports impacting all targets matches no rule." + }, + "description": "Rules changing how PRs are batched based on the build targets they impact." + }, "directMergeMode": { "type": "string", "enum": [ @@ -963,6 +2614,26 @@ ], "description": "The Git strategy used to merge a PR into the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-method for details." }, + "testBranchConstructionMode": { + "type": "string", + "enum": [ + "rename_temp_branch", + "push_new_branch_from_temp" + ], + "description": "How the merge queue turns its built temporary branch into the `trunk-merge` branch CI runs on. `rename_temp_branch` renames the ref. `push_new_branch_from_temp` creates the final ref at the temporary branch's head commit and deletes the temporary ref, which needs no rename permission — use it when an organization- or enterprise-level ruleset targets these branches, since GitHub's rename restriction is the one rule an exempt bypass actor cannot lift." + }, + "enqueueingLabel": { + "type": "string", + "description": "The GitHub label whose application enqueues a PR onto the merge queue." + }, + "labelCommandsEnabled": { + "type": "boolean", + "description": "Whether label-based commands (e.g. enqueue/dequeue via labels) are enabled on the merge queue." + }, + "stateLabelsEnabled": { + "type": "boolean", + "description": "Whether the merge queue applies labels to PRs reflecting their merge queue state." + }, "enqueuedPullRequests": { "type": "array", "items": { @@ -1032,6 +2703,9 @@ "prAuthor" ] } + }, + "notReadyTimeoutHours": { + "type": "number" } }, "required": [ @@ -1049,12 +2723,20 @@ "commentsEnabled", "commandsEnabled", "statusCheckEnabled", + "extensionEnabled", "bisectionConcurrency", "requiredStatuses", + "allowedBotSubmitters", + "batchingRules", "directMergeMode", "optimizationMode", "mergeMethod", - "enqueuedPullRequests" + "testBranchConstructionMode", + "enqueueingLabel", + "labelCommandsEnabled", + "stateLabelsEnabled", + "enqueuedPullRequests", + "notReadyTimeoutHours" ] } } @@ -1163,15 +2845,15 @@ }, "testingTimeoutMinutes": { "type": "integer", - "minimum": 1, + "minimum": 0, "maximum": 4294967295, - "description": "The maximum number of minutes the merge queue will wait for tests to complete before timing out." + "description": "The maximum number of minutes the merge queue will wait for tests to complete before timing out. Set to 0 to disable the timeout." }, "pendingFailureDepth": { "type": "integer", - "minimum": 1, + "minimum": 0, "maximum": 4294967295, - "description": "When enabled, PRs that fail tests will wait for the specified number of PRs below them to finish testing before getting kicked from the queue. This works best with optimistic merging enabled." + "description": "When enabled, PRs that fail tests will wait for the specified number of PRs below them to finish testing before getting kicked from the queue. This works best with optimistic merging enabled. Set to 0 to disable." }, "canOptimisticallyMerge": { "type": "boolean", @@ -1238,10 +2920,22 @@ ], "description": "The Git merge method used when merging PRs into the target branch. Valid values: merge_commit, squash, rebase." }, + "testBranchConstructionMode": { + "type": "string", + "enum": [ + "rename_temp_branch", + "push_new_branch_from_temp" + ], + "description": "How the merge queue builds the branch CI runs on. Valid values: rename_temp_branch, push_new_branch_from_temp." + }, "statusCheckEnabled": { "type": "boolean", "description": "Post a GitHub status check on PRs with the status of the PR in the merge queue." }, + "extensionEnabled": { + "type": "boolean", + "description": "Whether the Trunk Merge Queue browser extension is enabled (shown) for this repository." + }, "requiredStatuses": { "type": "array", "items": { @@ -1252,6 +2946,58 @@ "deleteRequiredStatuses": { "type": "boolean", "description": "Removes a manually specified set of required statuses. After this, the statuses that must pass when the merge queue performs testing will be pulled from either GitHub branch protection settings or your `.trunk/trunk.yaml`." + }, + "allowedBotSubmitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Sets the GitHub logins of bot/app accounts (e.g. `dependabot[bot]`) whose PRs are allowed to be submitted to the merge queue. This replaces the existing set. Pass an empty list to clear all allowed bot submitters." + }, + "batchingRules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "targetPattern": { + "type": "string", + "minLength": 1, + "description": "The impacted-target label this rule applies to. Matched exactly, or as a prefix when it ends in a single `*` (e.g. `//db/migrations:*`). A `*` anywhere other than the last character is rejected, and `*` on its own is rejected — a rule matching every target is a queue-wide setting rather than a rule." + }, + "policy": { + "type": "string", + "enum": [ + "isolate" + ], + "description": "What to do with a PR whose impacted targets match. `isolate` tests it on its own, exactly as `/trunk merge --no-batch` does." + } + }, + "required": [ + "targetPattern", + "policy" + ], + "description": "A rule that changes how a PR is batched based on the build targets it impacts. Evaluated from the impacted targets uploaded for the PR's head commit each time the queue forms batches, so it follows pushes that add or remove a matching target. A PR that reports impacting all targets matches no rule." + }, + "description": "Sets how PRs are batched based on the build targets they impact, for queues in parallel mode that upload impacted targets. This replaces the existing set of rules. Pass an empty list to clear all batching rules." + }, + "enqueueingLabel": { + "type": "string", + "minLength": 1, + "description": "The GitHub label whose application enqueues a PR onto the merge queue." + }, + "labelCommandsEnabled": { + "type": "boolean", + "description": "Whether label-based commands (e.g. enqueue/dequeue via labels) are enabled on the merge queue." + }, + "stateLabelsEnabled": { + "type": "boolean", + "description": "Whether the merge queue applies labels to PRs reflecting their merge queue state." + }, + "notReadyTimeoutHours": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "The number of hours a PR can remain submitted but not mergeable before it is removed from the queue. Set to 0 to disable the timeout." } }, "required": [ @@ -1323,6 +3069,10 @@ "statusCheckEnabled": { "type": "boolean" }, + "extensionEnabled": { + "type": "boolean", + "description": "Whether the Trunk Merge Queue browser extension is enabled (shown) for this repository." + }, "bisectionConcurrency": { "type": "number" }, @@ -1332,6 +3082,39 @@ "type": "string" } }, + "allowedBotSubmitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The GitHub logins of bot/app accounts (e.g. `dependabot[bot]`) whose PRs are allowed to be submitted to the merge queue." + }, + "batchingRules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "targetPattern": { + "type": "string", + "minLength": 1, + "description": "The impacted-target label this rule applies to. Matched exactly, or as a prefix when it ends in a single `*` (e.g. `//db/migrations:*`). A `*` anywhere other than the last character is rejected, and `*` on its own is rejected — a rule matching every target is a queue-wide setting rather than a rule." + }, + "policy": { + "type": "string", + "enum": [ + "isolate" + ], + "description": "What to do with a PR whose impacted targets match. `isolate` tests it on its own, exactly as `/trunk merge --no-batch` does." + } + }, + "required": [ + "targetPattern", + "policy" + ], + "description": "A rule that changes how a PR is batched based on the build targets it impacts. Evaluated from the impacted targets uploaded for the PR's head commit each time the queue forms batches, so it follows pushes that add or remove a matching target. A PR that reports impacting all targets matches no rule." + }, + "description": "Rules changing how PRs are batched based on the build targets they impact." + }, "directMergeMode": { "type": "string", "enum": [ @@ -1356,6 +3139,29 @@ "rebase" ], "description": "The Git strategy used to merge a PR into the target branch. See https://docs.trunk.io/merge-queue/administration/advanced-settings#merge-method for details." + }, + "testBranchConstructionMode": { + "type": "string", + "enum": [ + "rename_temp_branch", + "push_new_branch_from_temp" + ], + "description": "How the merge queue turns its built temporary branch into the `trunk-merge` branch CI runs on. `rename_temp_branch` renames the ref. `push_new_branch_from_temp` creates the final ref at the temporary branch's head commit and deletes the temporary ref, which needs no rename permission — use it when an organization- or enterprise-level ruleset targets these branches, since GitHub's rename restriction is the one rule an exempt bypass actor cannot lift." + }, + "enqueueingLabel": { + "type": "string", + "description": "The GitHub label whose application enqueues a PR onto the merge queue." + }, + "labelCommandsEnabled": { + "type": "boolean", + "description": "Whether label-based commands (e.g. enqueue/dequeue via labels) are enabled on the merge queue." + }, + "stateLabelsEnabled": { + "type": "boolean", + "description": "Whether the merge queue applies labels to PRs reflecting their merge queue state." + }, + "notReadyTimeoutHours": { + "type": "number" } }, "required": [ @@ -1373,11 +3179,19 @@ "commentsEnabled", "commandsEnabled", "statusCheckEnabled", + "extensionEnabled", "bisectionConcurrency", "requiredStatuses", + "allowedBotSubmitters", + "batchingRules", "directMergeMode", "optimizationMode", - "mergeMethod" + "mergeMethod", + "testBranchConstructionMode", + "enqueueingLabel", + "labelCommandsEnabled", + "stateLabelsEnabled", + "notReadyTimeoutHours" ] } } @@ -1752,9 +3566,12 @@ "enum": [ "QUEUED", "IN_PROGRESS", - "COMPLETED" + "COMPLETED", + "PENDING", + "WAITING", + "REQUESTED" ], - "description": "The status of a GitHub check run. Mirrors GitHub's check run status values." + "description": "The status of a GitHub check run. Mirrors GitHub's check run status values. `WAITING` and `PENDING` are the deployment-gate states — a check run sitting in one of them is waiting on a manual approval, not running." }, "conclusion": { "type": "string", @@ -1783,93 +3600,306 @@ "checkRuns" ] }, - "description": "GitHub check suites reported against the test branch." + "description": "GitHub check suites reported against the test branch." + }, + "statusChecks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "context": { + "type": "string", + "description": "The context (name) of the status check as posted to GitHub (e.g. `ci/lint`)." + }, + "url": { + "type": "string", + "description": "URL with more details about this status check, if any." + }, + "state": { + "type": "string", + "enum": [ + "ERROR", + "FAILURE", + "PENDING", + "SUCCESS" + ], + "description": "The state of a GitHub commit status check. Mirrors GitHub's commit status state values." + } + }, + "required": [ + "context" + ] + }, + "description": "GitHub commit status checks reported against the test branch SHA." + }, + "testedPullRequests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "prNumber": { + "type": "number", + "description": "The pull request number on the Git provider." + }, + "prUrl": { + "type": "string", + "description": "URL of the pull request on the Git provider." + }, + "title": { + "type": "string", + "description": "The title of the pull request." + } + }, + "required": [ + "prNumber", + "prUrl", + "title" + ] + }, + "description": "The pull requests that this test run is testing. Contains multiple entries when batching is enabled." + }, + "impactedTargets": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The union of impacted build/test targets across all PRs involved in the test run, including any dependent PRs previously merged into the test branch. Only present when impacted targets are being uploaded for the repository." + }, + "impactedTargetsForTestedPrs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The impacted build/test targets for only the PRs being tested in this run (i.e. `testedPullRequests`), excluding any dependent PRs. Only present when impacted targets are being uploaded for the repository." + }, + "dependentPrs": { + "type": "array", + "items": { + "type": "number" + }, + "description": "PR numbers of other PRs this test run depends on but is not itself testing. Populated in parallel-mode queues when previously-passed PRs ahead of the tested PR are merged into the test branch to form the predicted base." + } + }, + "required": [ + "requiredStatuses", + "testBranch", + "testBranchSha", + "checkSuites", + "statusChecks", + "testedPullRequests" + ] + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/plain-text": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/listMergeQueueTestingResults": { + "post": { + "security": [ + { + "ApiKeyAuth": [] + } + ], + "summary": "List completed merge queue testing for a time range", + "description": "Returns the stretches of testing a merge queue completed in the given range, newest first. One entry per pull request per attempt: a pull request appears several times if its testing restarted, and a batched test run appears once per pull request it tested. Testing still in progress is not included. Pass an entry's `testRunId` to `/getMergeQueueTestingDetails` for the run's check suites, statuses and tested pull requests.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "repo": { + "type": "object", + "properties": { + "host": { + "type": "string", + "description": "The host of the repository.", + "examples": [ + "github.com" + ] + }, + "owner": { + "type": "string", + "description": "The owner of the repository.", + "examples": [ + "trunk-io" + ] + }, + "name": { + "type": "string", + "description": "The name of the repository.", + "examples": [ + "trunk" + ] + } }, - "statusChecks": { + "required": [ + "host", + "owner", + "name" + ], + "description": "The repository whose merge queue ran the testing." + }, + "targetBranch": { + "type": "string", + "description": "The target branch of the merge queue.", + "examples": [ + "main" + ] + }, + "since": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp (inclusive). Only testing that finished at or after this time is returned. Must be no more than 45 days before `until`; merge metrics are retained for 45 days, so anything earlier returns nothing.", + "examples": [ + "2024-01-01T00:00:00Z" + ] + }, + "until": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp (inclusive) bounding the upper end of the range. Defaults to now.", + "examples": [ + "2024-01-08T00:00:00Z" + ] + }, + "offset": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of results to skip. Defaults to 0." + }, + "take": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Number of results to return (1-100). Defaults to 50." + } + }, + "required": [ + "repo", + "targetBranch", + "since" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "testingResults": { "type": "array", "items": { "type": "object", "properties": { - "context": { + "prNumber": { + "type": "number", + "description": "The pull request number on the Git provider." + }, + "endedAt": { "type": "string", - "description": "The context (name) of the status check as posted to GitHub (e.g. `ci/lint`)." + "description": "ISO 8601 timestamp of when this stretch of testing ended. Recorded to whole-second precision. This is the end of the testing itself, not of the pull request's queue attempt — see `cycleConclusion`." }, - "url": { + "testingDurationMs": { + "type": "number", + "description": "How long this stretch of testing lasted, in milliseconds. Recorded to whole-second precision, so this is always a multiple of 1000." + }, + "outcome": { "type": "string", - "description": "URL with more details about this status check, if any." + "enum": [ + "passed", + "failed", + "interrupted", + "cancelled" + ], + "description": "How this stretch of testing ended. `passed` — the test run completed and passed (including a successful bisection step). `failed` — the test run completed and failed, or the pull request entered bisection. `interrupted` — testing was cut short and will be retried (a restart, a preempt, or a base branch change). `cancelled` — the pull request left the queue while testing." }, - "state": { + "cycleConclusion": { "type": "string", "enum": [ - "ERROR", - "FAILURE", - "PENDING", - "SUCCESS" + "merged", + "failed", + "cancelled" ], - "description": "The state of a GitHub commit status check. Mirrors GitHub's commit status state values." - } - }, - "required": [ - "context" - ] - }, - "description": "GitHub commit status checks reported against the test branch SHA." - }, - "testedPullRequests": { - "type": "array", - "items": { - "type": "object", - "properties": { - "prNumber": { - "type": "number", - "description": "The pull request number on the Git provider." + "description": "How the pull request's queue attempt ultimately ended. Absent while the attempt is still in flight." }, - "prUrl": { + "bisection": { "type": "string", - "description": "URL of the pull request on the Git provider." + "enum": [ + "in_bisection", + "entered_bisection" + ], + "description": "The pull request's relationship to bisection at this point. `entered_bisection` — this is the failure that caused its batch to be split. `in_bisection` — this testing was itself part of a bisection. Absent when bisection was not involved. A result that is both is reported as `entered_bisection`." }, - "title": { + "testRunId": { "type": "string", - "description": "The title of the pull request." + "description": "The test run this testing belongs to; pass it to `/getMergeQueueTestingDetails` for the run's check suites, statuses and tested pull requests. Absent on results recorded before test run IDs were tracked on these events." } }, "required": [ "prNumber", - "prUrl", - "title" + "testingDurationMs" ] }, - "description": "The pull requests that this test run is testing. Contains multiple entries when batching is enabled." - }, - "impactedTargets": { - "type": "array", - "items": { - "type": "string" - }, - "description": "The union of impacted build/test targets across all PRs involved in the test run, including any dependent PRs previously merged into the test branch. Only present when impacted targets are being uploaded for the repository." - }, - "impactedTargetsForTestedPrs": { - "type": "array", - "items": { - "type": "string" - }, - "description": "The impacted build/test targets for only the PRs being tested in this run (i.e. `testedPullRequests`), excluding any dependent PRs. Only present when impacted targets are being uploaded for the repository." + "description": "Completed stretches of merge queue testing, newest first. One entry per pull request per attempt, so a pull request appears several times if its testing restarted, and a batched test run appears once per pull request it tested. Testing still in progress is not included." }, - "dependentPrs": { - "type": "array", - "items": { - "type": "number" - }, - "description": "PR numbers of other PRs this test run depends on but is not itself testing. Populated in parallel-mode queues when previously-passed PRs ahead of the tested PR are merged into the test branch to form the predicted base." + "totalItems": { + "type": "number", + "description": "The total number of results matching the request, ignoring `offset` and `take`." } }, "required": [ - "requiredStatuses", - "testBranch", - "testBranchSha", - "checkSuites", - "statusChecks", - "testedPullRequests" + "testingResults", + "totalItems" ] } } @@ -2022,7 +4052,8 @@ "maximum": 4294967295 }, "sha": { - "type": "string" + "type": "string", + "pattern": "^[A-Za-z0-9]+$" } }, "required": [ @@ -2304,7 +4335,7 @@ }, "org_url_slug": { "type": "string", - "description": "The slug of your organization. Find this at https://app.trunk.io/trunk/settings under \"Organization Name\" > \"Slug\"", + "description": "The slug of your organization. This is the unique identifier for your organization, for example: https://app.trunk.io/", "examples": [ "my-trunk-org-slug" ] @@ -2420,6 +4451,17 @@ "variant": { "type": "string", "description": "The variant of the test case." + }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test case, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test case." } }, "required": [ @@ -2433,7 +4475,8 @@ "quarantined_at", "status_last_updated_at", "test_case_id", - "variant" + "variant", + "labels" ], "description": "A quarantined test case." }, @@ -2554,7 +4597,7 @@ }, "org_url_slug": { "type": "string", - "description": "The slug of your organization. Find this at https://app.trunk.io/trunk/settings under \"Organization Name\" > \"Slug\"", + "description": "The slug of your organization. This is the unique identifier for your organization, for example: https://app.trunk.io/", "examples": [ "my-trunk-org-slug" ] @@ -2712,6 +4755,17 @@ "required": [ "html_url" ] + }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test." } }, "required": [ @@ -2723,7 +4777,8 @@ "status", "codeowners", "pull_requests_impacted_last_7d", - "quarantined" + "quarantined", + "labels" ] }, "description": "A page of unhealthy test cases." @@ -2843,7 +4898,7 @@ }, "org_url_slug": { "type": "string", - "description": "The slug of your organization. Find this at https://app.trunk.io/trunk/settings under \"Organization Name\" > \"Slug\"", + "description": "The slug of your organization. This is the unique identifier for your organization, for example: https://app.trunk.io/", "examples": [ "my-trunk-org-slug" ] @@ -3039,6 +5094,17 @@ "required": [ "html_url" ] + }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test." } }, "required": [ @@ -3053,7 +5119,8 @@ "failure_rate_last_24h", "codeowners", "pull_requests_impacted_last_7d", - "quarantined" + "quarantined", + "labels" ] }, "description": "A page of failing test cases." @@ -3173,7 +5240,7 @@ }, "org_url_slug": { "type": "string", - "description": "The slug of your organization. Find this at https://app.trunk.io/trunk/settings under \"Organization Name\" > \"Slug\"", + "description": "The slug of your organization. This is the unique identifier for your organization, for example: https://app.trunk.io/", "examples": [ "my-trunk-org-slug" ] @@ -3341,6 +5408,17 @@ "required": [ "html_url" ] + }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test." } }, "required": [ @@ -3355,7 +5433,8 @@ "failure_rate_last_24h", "codeowners", "pull_requests_impacted_last_7d", - "quarantined" + "quarantined", + "labels" ], "description": "The details of a test case." } @@ -3997,6 +6076,17 @@ "html_url" ] }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test." + }, "test_suite": { "type": "string", "description": "The test suite of the test (deprecated, use `parent` instead)" @@ -4014,7 +6104,8 @@ "failure_rate_last_24h", "codeowners", "pull_requests_impacted_last_7d", - "quarantined" + "quarantined", + "labels" ] }, "quarantine_setting_changed": { @@ -4123,6 +6214,10 @@ "ticket": { "html_url": "http://example.com" }, + "bazel_label": "string", + "labels": [ + "string" + ], "test_suite": "string" }, "quarantine_setting_changed": { @@ -4297,6 +6392,17 @@ "html_url" ] }, + "bazel_label": { + "type": "string", + "description": "The bazel label (target) of the test, when available." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The names of the labels currently assigned to the test." + }, "test_suite": { "type": "string", "description": "The test suite of the test (deprecated, use `parent` instead)" @@ -4314,7 +6420,8 @@ "failure_rate_last_24h", "codeowners", "pull_requests_impacted_last_7d", - "quarantined" + "quarantined", + "labels" ] }, "status_change": { @@ -4406,6 +6513,10 @@ "ticket": { "html_url": "http://example.com" }, + "bazel_label": "string", + "labels": [ + "string" + ], "test_suite": "string" }, "status_change": { @@ -4423,11 +6534,11 @@ "responses": {} } }, - "pull_request.failed": { + "pull_request_batch.canceled": { "post": { - "operationId": "pull_request.failed", - "summary": "Pull request failed", - "description": "Triggered when a PR fails while in the merge queue", + "operationId": "pull_request_batch.canceled", + "summary": "Pull request batch canceled", + "description": "Triggered when a batch of PRs is canceled", "security": [], "requestBody": { "content": { @@ -4448,31 +6559,24 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "batched": { - "type": "boolean", - "description": "Whether this pull request was part of a batch" - }, - "failure_reason": { + "cancellation_reason": { "type": "string", "enum": [ - "START_TEST_RUN_INVALID_EVENT", - "START_TEST_RUN_MERGE_CONFLICT", - "START_TEST_RUN_CONFIG_NOT_FOUND", - "START_TEST_RUN_CONFIG_PARSING_FAILURE", - "START_TEST_RUN_CONFIG_MISSING_REQUIRED_STATUSES", - "START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES", - "START_TEST_RUN_CONFIG_BAD_VERSION", - "START_TEST_RUN_NO_REQUIRED_STATUSES", - "TEST_RUN_REQUIRED_STATUS_FAILED", - "TEST_RUN_TIMEOUT", - "GITHUB_API_MERGE_PR_FAILED", - "GITHUB_API_DIRECT_MERGE_PR_FAILED", - "PR_UPDATED_AT_MERGE_TIME", - "START_TEST_RUN_RETRY_EXHAUSTED", - "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", - "TEST_RUN_FAILED_BY_OPTIMIZATION" + "USER_REQUESTED", + "PR_CLOSED", + "PR_PUSHED_TO", + "PR_BASE_BRANCH_CHANGED", + "TRUNK_ADMIN_REQUESTED", + "PR_CONVERTED_TO_DRAFT", + "STACKED_PR_MEMBER_PUSHED_TO", + "STACKED_PR_MEMBER_CLOSED", + "STACKED_PR_MEMBER_MERGED", + "STACKED_PR_MEMBER_BASE_BRANCH_CHANGED", + "NOT_READY_TIMEOUT_EXPIRED", + "STACKED_PR_STACK_CHANGED", + "STACKED_PR_GROUP_CANCELLED_AT_MERGE_TIME" ], - "description": "The reason the PR failed" + "description": "The reason the batch was canceled" }, "is_bisection": { "type": "boolean", @@ -4480,27 +6584,29 @@ }, "type": { "type": "string", - "const": "pull_request.failed", + "const": "pull_request_batch.canceled", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "failed", + "const": "canceled", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -4527,8 +6633,15 @@ }, "status": { "type": "string", - "const": "failed", - "description": "The current status of the PR" + "const": "canceled", + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -4541,37 +6654,42 @@ } }, "required": [ + "test_branch", + "test_branch_sha", "is_bisection", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR fails while in the merge queue" + "description": "Triggered when a batch of PRs is canceled" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "batched": true, - "failure_reason": "START_TEST_RUN_INVALID_EVENT", + "cancellation_reason": "USER_REQUESTED", "is_bisection": true, - "type": "pull_request.failed", - "action": "failed", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "type": "pull_request_batch.canceled", + "action": "canceled", + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "failed", + "status": "canceled", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -4581,11 +6699,11 @@ "responses": {} } }, - "pull_request.pending_failure": { + "pull_request_batch.failed": { "post": { - "operationId": "pull_request.pending_failure", - "summary": "Pull request pending failure", - "description": "Triggered when a PR enters pending failure state while in the merge queue", + "operationId": "pull_request_batch.failed", + "summary": "Pull request batch failed", + "description": "Triggered when a batch of PRs fails while in the merge queue", "security": [], "requestBody": { "content": { @@ -4606,10 +6724,6 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "batched": { - "type": "boolean", - "description": "Whether this pull request was part of a batch" - }, "failure_reason": { "type": "string", "enum": [ @@ -4625,36 +6739,47 @@ "TEST_RUN_TIMEOUT", "GITHUB_API_MERGE_PR_FAILED", "GITHUB_API_DIRECT_MERGE_PR_FAILED", + "GITHUB_API_RATE_LIMIT_EXCEEDED", "PR_UPDATED_AT_MERGE_TIME", "START_TEST_RUN_RETRY_EXHAUSTED", "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", - "TEST_RUN_FAILED_BY_OPTIMIZATION" + "TEST_RUN_FAILED_BY_OPTIMIZATION", + "GITHUB_API_BRANCH_PROTECTION_UNMET", + "GITHUB_API_MERGE_ALREADY_IN_PROGRESS", + "GITHUB_API_REPEATED_SERVER_ERRORS", + "START_TEST_RUN_PERMISSIONS_BLOCK_TEST_BRANCH" ], - "description": "The reason the PR is pending failure" + "description": "The reason the batch failed" + }, + "is_bisection": { + "type": "boolean", + "description": "Whether this event is part of a bisection test run" }, "type": { "type": "string", - "const": "pull_request.pending_failure", + "const": "pull_request_batch.failed", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "pending_failure", + "const": "failed", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -4681,8 +6806,15 @@ }, "status": { "type": "string", - "const": "pending_failure", - "description": "The current status of the PR" + "const": "failed", + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -4695,35 +6827,42 @@ } }, "required": [ + "test_branch", + "test_branch_sha", + "is_bisection", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR enters pending failure state while in the merge queue" + "description": "Triggered when a batch of PRs fails while in the merge queue" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "batched": true, "failure_reason": "START_TEST_RUN_INVALID_EVENT", - "type": "pull_request.pending_failure", - "action": "pending_failure", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "is_bisection": true, + "type": "pull_request_batch.failed", + "action": "failed", + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "pending_failure", + "status": "failed", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -4733,11 +6872,11 @@ "responses": {} } }, - "pull_request.canceled": { + "pull_request_batch.merged": { "post": { - "operationId": "pull_request.canceled", - "summary": "Pull request canceled", - "description": "Triggered when a PR is canceled", + "operationId": "pull_request_batch.merged", + "summary": "Pull request batch merged", + "description": "Triggered when the last pull request in a batch gets merged", "security": [], "requestBody": { "content": { @@ -4758,53 +6897,40 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "batched": { - "type": "boolean", - "description": "Whether this pull request was part of a batch" - }, - "cancellation_reason": { + "merged_reason": { "type": "string", "enum": [ - "USER_REQUESTED", - "PR_CLOSED", - "PR_PUSHED_TO", - "PR_BASE_BRANCH_CHANGED", - "TRUNK_ADMIN_REQUESTED", - "PR_CONVERTED_TO_DRAFT", - "STACKED_PR_MEMBER_PUSHED_TO", - "STACKED_PR_MEMBER_CLOSED", - "STACKED_PR_MEMBER_MERGED", - "STACKED_PR_MEMBER_BASE_BRANCH_CHANGED" + "MERGE_GRAPH_MERGE", + "MANUAL_MERGE", + "MERGE_GRAPH_DIRECT_MERGE" ], - "description": "The reason the PR was canceled" - }, - "is_bisection": { - "type": "boolean", - "description": "Whether this event is part of a bisection test run" + "description": "The reason the batch was merged" }, "type": { "type": "string", - "const": "pull_request.canceled", + "const": "pull_request_batch.merged", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "canceled", + "const": "merged", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -4831,8 +6957,15 @@ }, "status": { "type": "string", - "const": "canceled", - "description": "The current status of the PR" + "const": "merged", + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -4845,37 +6978,40 @@ } }, "required": [ - "is_bisection", + "test_branch", + "test_branch_sha", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR is canceled" + "description": "Triggered when the last pull request in a batch gets merged" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "batched": true, - "cancellation_reason": "USER_REQUESTED", - "is_bisection": true, - "type": "pull_request.canceled", - "action": "canceled", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "merged_reason": "MERGE_GRAPH_MERGE", + "type": "pull_request_batch.merged", + "action": "merged", + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "canceled", + "status": "merged", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -4885,11 +7021,11 @@ "responses": {} } }, - "pull_request.merged": { + "pull_request_batch.pending_failure": { "post": { - "operationId": "pull_request.merged", - "summary": "Pull request merged", - "description": "Triggered when a PR is merged", + "operationId": "pull_request_batch.pending_failure", + "summary": "Pull request batch pending failure", + "description": "Triggered when the last pull request in a batch enters pending failure state", "security": [], "requestBody": { "content": { @@ -4910,42 +7046,58 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "batched": { - "type": "boolean", - "description": "Whether this pull request was part of a batch" - }, - "merged_reason": { + "failure_reason": { "type": "string", "enum": [ - "MERGE_GRAPH_MERGE", - "MANUAL_MERGE", - "MERGE_GRAPH_DIRECT_MERGE" + "START_TEST_RUN_INVALID_EVENT", + "START_TEST_RUN_MERGE_CONFLICT", + "START_TEST_RUN_CONFIG_NOT_FOUND", + "START_TEST_RUN_CONFIG_PARSING_FAILURE", + "START_TEST_RUN_CONFIG_MISSING_REQUIRED_STATUSES", + "START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES", + "START_TEST_RUN_CONFIG_BAD_VERSION", + "START_TEST_RUN_NO_REQUIRED_STATUSES", + "TEST_RUN_REQUIRED_STATUS_FAILED", + "TEST_RUN_TIMEOUT", + "GITHUB_API_MERGE_PR_FAILED", + "GITHUB_API_DIRECT_MERGE_PR_FAILED", + "GITHUB_API_RATE_LIMIT_EXCEEDED", + "PR_UPDATED_AT_MERGE_TIME", + "START_TEST_RUN_RETRY_EXHAUSTED", + "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", + "TEST_RUN_FAILED_BY_OPTIMIZATION", + "GITHUB_API_BRANCH_PROTECTION_UNMET", + "GITHUB_API_MERGE_ALREADY_IN_PROGRESS", + "GITHUB_API_REPEATED_SERVER_ERRORS", + "START_TEST_RUN_PERMISSIONS_BLOCK_TEST_BRANCH" ], - "description": "The reason the PR was merged" + "description": "The reason the batch is pending failure" }, "type": { "type": "string", - "const": "pull_request.merged", + "const": "pull_request_batch.pending_failure", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "merged", + "const": "pending_failure", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -4972,8 +7124,15 @@ }, "status": { "type": "string", - "const": "merged", - "description": "The current status of the PR" + "const": "pending_failure", + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -4986,35 +7145,40 @@ } }, "required": [ + "test_branch", + "test_branch_sha", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR is merged" + "description": "Triggered when the last pull request in a batch enters pending failure state" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "batched": true, - "merged_reason": "MERGE_GRAPH_MERGE", - "type": "pull_request.merged", - "action": "merged", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "failure_reason": "START_TEST_RUN_INVALID_EVENT", + "type": "pull_request_batch.pending_failure", + "action": "pending_failure", + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "merged", + "status": "pending_failure", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5024,11 +7188,11 @@ "responses": {} } }, - "pull_request.queued": { + "pull_request_batch.queued": { "post": { - "operationId": "pull_request.queued", - "summary": "Pull request queued", - "description": "Triggered when a PR has passed any branch protection requirements and is ready to be tested in the merge queue", + "operationId": "pull_request_batch.queued", + "summary": "Pull request batch queued", + "description": "Triggered when a batch of PRs is queued", "security": [], "requestBody": { "content": { @@ -5036,6 +7200,19 @@ "schema": { "type": "object", "properties": { + "test_branch": { + "type": "string", + "description": "The branch the pull request or pull request batch was tested on" + }, + "test_branch_sha": { + "type": "string", + "description": "The SHA of the branch the pull request or pull request batch was tested on" + }, + "test_pr_number": { + "type": "integer", + "minimum": 0, + "description": "The number of the pull request used to test the pull request or pull request batch" + }, "queued_reason": { "type": "string", "enum": [ @@ -5050,11 +7227,11 @@ "BISECTION_REQUIRED", "BISECTION_TEST_RUN_PASSED" ], - "description": "The reason the PR was queued" + "description": "The reason the batch was queued" }, "type": { "type": "string", - "const": "pull_request.queued", + "const": "pull_request_batch.queued", "description": "The type of webhook event that occurred" }, "action": { @@ -5062,19 +7239,21 @@ "const": "queued", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -5102,7 +7281,14 @@ "status": { "type": "string", "const": "queued", - "description": "The current status of the PR" + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5115,31 +7301,40 @@ } }, "required": [ + "test_branch", + "test_branch_sha", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR has passed any branch protection requirements and is ready to be tested in the merge queue" + "description": "Triggered when a batch of PRs is queued" }, "example": { + "test_branch": "string", + "test_branch_sha": "string", + "test_pr_number": 0, "queued_reason": "MANUAL_PUSH_TO_TARGET_BRANCH", - "type": "pull_request.queued", + "type": "pull_request_batch.queued", "action": "queued", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "queued", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5149,11 +7344,11 @@ "responses": {} } }, - "pull_request.submitted": { + "pull_request_batch.submitted": { "post": { - "operationId": "pull_request.submitted", - "summary": "Pull request submitted", - "description": "Triggered when a PR is submitted to Trunk Merge", + "operationId": "pull_request_batch.submitted", + "summary": "Pull request batch submitted", + "description": "Triggered when a batch of PRs is submitted", "security": [], "requestBody": { "content": { @@ -5161,6 +7356,19 @@ "schema": { "type": "object", "properties": { + "test_branch": { + "type": "string", + "description": "The branch the pull request or pull request batch was tested on" + }, + "test_branch_sha": { + "type": "string", + "description": "The SHA of the branch the pull request or pull request batch was tested on" + }, + "test_pr_number": { + "type": "integer", + "minimum": 0, + "description": "The number of the pull request used to test the pull request or pull request batch" + }, "submitted_reason": { "type": "string", "enum": [ @@ -5168,11 +7376,11 @@ "TRUNK_ADMIN_REQUESTED", "API_REQUESTED" ], - "description": "The reason the PR was submitted" + "description": "The reason the batch was submitted" }, "type": { "type": "string", - "const": "pull_request.submitted", + "const": "pull_request_batch.submitted", "description": "The type of webhook event that occurred" }, "action": { @@ -5180,19 +7388,21 @@ "const": "submitted", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -5220,7 +7430,14 @@ "status": { "type": "string", "const": "submitted", - "description": "The current status of the PR" + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5233,31 +7450,40 @@ } }, "required": [ + "test_branch", + "test_branch_sha", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR is submitted to Trunk Merge" + "description": "Triggered when a batch of PRs is submitted" }, "example": { + "test_branch": "string", + "test_branch_sha": "string", + "test_pr_number": 0, "submitted_reason": "USER_REQUESTED", - "type": "pull_request.submitted", + "type": "pull_request_batch.submitted", "action": "submitted", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "submitted", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5267,11 +7493,11 @@ "responses": {} } }, - "pull_request.testing": { + "pull_request_batch.testing": { "post": { - "operationId": "pull_request.testing", - "summary": "Pull request testing", - "description": "Triggered when a PR has started testing in the merge queue", + "operationId": "pull_request_batch.testing", + "summary": "Pull request batch testing", + "description": "Triggered when all pull requests in a batch start testing in the merge queue", "security": [], "requestBody": { "content": { @@ -5292,17 +7518,13 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "batched": { - "type": "boolean", - "description": "Whether this pull request was part of a batch" - }, "is_bisection": { "type": "boolean", "description": "Whether this event is part of a bisection test run" }, "type": { "type": "string", - "const": "pull_request.testing", + "const": "pull_request_batch.testing", "description": "The type of webhook event that occurred" }, "action": { @@ -5310,19 +7532,21 @@ "const": "testing", "description": "The type of action that triggered the webhook" }, - "author": { - "type": "string", - "description": "The username of the author of the PR" - }, - "http_details_url": { - "type": "string", - "format": "uri", - "description": "Web link to the details about this PR" + "pr_numbers": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of the pull requests in the batch" }, - "pr_number": { - "type": "integer", - "minimum": 0, - "description": "The PR number" + "pr_numbers_in_batch": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." }, "repository": { "type": "object", @@ -5350,7 +7574,14 @@ "status": { "type": "string", "const": "testing", - "description": "The current status of the PR" + "description": "The current status of the Pull Request batch" + }, + "submitters": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The usernames of the users who submitted the PRs in the batch to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5363,36 +7594,41 @@ } }, "required": [ + "test_branch", + "test_branch_sha", "is_bisection", "type", "action", - "author", - "http_details_url", - "pr_number", + "pr_numbers", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a PR has started testing in the merge queue" + "description": "Triggered when all pull requests in a batch start testing in the merge queue" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "batched": true, "is_bisection": true, - "type": "pull_request.testing", + "type": "pull_request_batch.testing", "action": "testing", - "author": "string", - "http_details_url": "http://example.com", - "pr_number": 0, + "pr_numbers": [ + 0 + ], + "pr_numbers_in_batch": [ + 0 + ], "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "testing", + "submitters": [ + "string" + ], "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5402,11 +7638,11 @@ "responses": {} } }, - "pull_request_batch.failed": { + "pull_request.canceled": { "post": { - "operationId": "pull_request_batch.failed", - "summary": "Pull request batch failed", - "description": "Triggered when a batch of PRs fails while in the merge queue", + "operationId": "pull_request.canceled", + "summary": "Pull request canceled", + "description": "Triggered when a PR is canceled", "security": [], "requestBody": { "content": { @@ -5427,27 +7663,28 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "failure_reason": { + "batched": { + "type": "boolean", + "description": "Whether this pull request was part of a batch" + }, + "cancellation_reason": { "type": "string", "enum": [ - "START_TEST_RUN_INVALID_EVENT", - "START_TEST_RUN_MERGE_CONFLICT", - "START_TEST_RUN_CONFIG_NOT_FOUND", - "START_TEST_RUN_CONFIG_PARSING_FAILURE", - "START_TEST_RUN_CONFIG_MISSING_REQUIRED_STATUSES", - "START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES", - "START_TEST_RUN_CONFIG_BAD_VERSION", - "START_TEST_RUN_NO_REQUIRED_STATUSES", - "TEST_RUN_REQUIRED_STATUS_FAILED", - "TEST_RUN_TIMEOUT", - "GITHUB_API_MERGE_PR_FAILED", - "GITHUB_API_DIRECT_MERGE_PR_FAILED", - "PR_UPDATED_AT_MERGE_TIME", - "START_TEST_RUN_RETRY_EXHAUSTED", - "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", - "TEST_RUN_FAILED_BY_OPTIMIZATION" + "USER_REQUESTED", + "PR_CLOSED", + "PR_PUSHED_TO", + "PR_BASE_BRANCH_CHANGED", + "TRUNK_ADMIN_REQUESTED", + "PR_CONVERTED_TO_DRAFT", + "STACKED_PR_MEMBER_PUSHED_TO", + "STACKED_PR_MEMBER_CLOSED", + "STACKED_PR_MEMBER_MERGED", + "STACKED_PR_MEMBER_BASE_BRANCH_CHANGED", + "NOT_READY_TIMEOUT_EXPIRED", + "STACKED_PR_STACK_CHANGED", + "STACKED_PR_GROUP_CANCELLED_AT_MERGE_TIME" ], - "description": "The reason the batch failed" + "description": "The reason the PR was canceled" }, "is_bisection": { "type": "boolean", @@ -5455,29 +7692,27 @@ }, "type": { "type": "string", - "const": "pull_request_batch.failed", + "const": "pull_request.canceled", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "failed", + "const": "canceled", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -5504,8 +7739,12 @@ }, "status": { "type": "string", - "const": "failed", - "description": "The current status of the Pull Request batch" + "const": "canceled", + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5518,39 +7757,38 @@ } }, "required": [ - "test_branch", - "test_branch_sha", "is_bisection", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a batch of PRs fails while in the merge queue" + "description": "Triggered when a PR is canceled" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "failure_reason": "START_TEST_RUN_INVALID_EVENT", + "batched": true, + "cancellation_reason": "USER_REQUESTED", "is_bisection": true, - "type": "pull_request_batch.failed", - "action": "failed", - "pr_numbers": [ - 0 - ], - "pr_numbers_in_batch": [ - 0 - ], + "type": "pull_request.canceled", + "action": "canceled", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "failed", + "status": "canceled", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5560,11 +7798,11 @@ "responses": {} } }, - "pull_request_batch.pending_failure": { + "pull_request.failed": { "post": { - "operationId": "pull_request_batch.pending_failure", - "summary": "Pull request batch pending failure", - "description": "Triggered when the last pull request in a batch enters pending failure state", + "operationId": "pull_request.failed", + "summary": "Pull request failed", + "description": "Triggered when a PR fails while in the merge queue", "security": [], "requestBody": { "content": { @@ -5585,6 +7823,10 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, + "batched": { + "type": "boolean", + "description": "Whether this pull request was part of a batch" + }, "failure_reason": { "type": "string", "enum": [ @@ -5600,38 +7842,70 @@ "TEST_RUN_TIMEOUT", "GITHUB_API_MERGE_PR_FAILED", "GITHUB_API_DIRECT_MERGE_PR_FAILED", + "GITHUB_API_RATE_LIMIT_EXCEEDED", "PR_UPDATED_AT_MERGE_TIME", "START_TEST_RUN_RETRY_EXHAUSTED", "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", - "TEST_RUN_FAILED_BY_OPTIMIZATION" + "TEST_RUN_FAILED_BY_OPTIMIZATION", + "GITHUB_API_BRANCH_PROTECTION_UNMET", + "GITHUB_API_MERGE_ALREADY_IN_PROGRESS", + "GITHUB_API_REPEATED_SERVER_ERRORS", + "START_TEST_RUN_PERMISSIONS_BLOCK_TEST_BRANCH" ], - "description": "The reason the batch is pending failure" + "description": "The reason the PR failed" + }, + "is_bisection": { + "type": "boolean", + "description": "Whether this event is part of a bisection test run" + }, + "failure_causing_statuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the required status check" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the check run or status check, when GitHub reported one" + }, + "conclusion": { + "type": "string", + "description": "The conclusion GitHub reported for the check, when known" + } + }, + "required": [ + "name" + ] + }, + "description": "The required status checks that caused the test run to fail. Populated when the failure reason is TEST_RUN_REQUIRED_STATUS_FAILED, and omitted for a failure unrelated to a test run or where the failing checks were not recorded." }, "type": { "type": "string", - "const": "pull_request_batch.pending_failure", + "const": "pull_request.failed", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "pending_failure", + "const": "failed", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -5658,8 +7932,12 @@ }, "status": { "type": "string", - "const": "pending_failure", - "description": "The current status of the Pull Request batch" + "const": "failed", + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5672,37 +7950,45 @@ } }, "required": [ - "test_branch", - "test_branch_sha", + "is_bisection", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when the last pull request in a batch enters pending failure state" + "description": "Triggered when a PR fails while in the merge queue" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, + "batched": true, "failure_reason": "START_TEST_RUN_INVALID_EVENT", - "type": "pull_request_batch.pending_failure", - "action": "pending_failure", - "pr_numbers": [ - 0 - ], - "pr_numbers_in_batch": [ - 0 + "is_bisection": true, + "failure_causing_statuses": [ + { + "name": "string", + "http_url": "http://example.com", + "conclusion": "string" + } ], + "type": "pull_request.failed", + "action": "failed", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "pending_failure", + "status": "failed", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5712,11 +7998,11 @@ "responses": {} } }, - "pull_request_batch.canceled": { + "pull_request.merged": { "post": { - "operationId": "pull_request_batch.canceled", - "summary": "Pull request batch canceled", - "description": "Triggered when a batch of PRs is canceled", + "operationId": "pull_request.merged", + "summary": "Pull request merged", + "description": "Triggered when a PR is merged", "security": [], "requestBody": { "content": { @@ -5737,51 +8023,42 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "cancellation_reason": { + "batched": { + "type": "boolean", + "description": "Whether this pull request was part of a batch" + }, + "merged_reason": { "type": "string", "enum": [ - "USER_REQUESTED", - "PR_CLOSED", - "PR_PUSHED_TO", - "PR_BASE_BRANCH_CHANGED", - "TRUNK_ADMIN_REQUESTED", - "PR_CONVERTED_TO_DRAFT", - "STACKED_PR_MEMBER_PUSHED_TO", - "STACKED_PR_MEMBER_CLOSED", - "STACKED_PR_MEMBER_MERGED", - "STACKED_PR_MEMBER_BASE_BRANCH_CHANGED" + "MERGE_GRAPH_MERGE", + "MANUAL_MERGE", + "MERGE_GRAPH_DIRECT_MERGE" ], - "description": "The reason the batch was canceled" - }, - "is_bisection": { - "type": "boolean", - "description": "Whether this event is part of a bisection test run" + "description": "The reason the PR was merged" }, "type": { "type": "string", - "const": "pull_request_batch.canceled", + "const": "pull_request.merged", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "canceled", + "const": "merged", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -5808,8 +8085,12 @@ }, "status": { "type": "string", - "const": "canceled", - "description": "The current status of the Pull Request batch" + "const": "merged", + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5822,39 +8103,36 @@ } }, "required": [ - "test_branch", - "test_branch_sha", - "is_bisection", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a batch of PRs is canceled" + "description": "Triggered when a PR is merged" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "cancellation_reason": "USER_REQUESTED", - "is_bisection": true, - "type": "pull_request_batch.canceled", - "action": "canceled", - "pr_numbers": [ - 0 - ], - "pr_numbers_in_batch": [ - 0 - ], + "batched": true, + "merged_reason": "MERGE_GRAPH_MERGE", + "type": "pull_request.merged", + "action": "merged", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "canceled", + "status": "merged", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -5864,11 +8142,11 @@ "responses": {} } }, - "pull_request_batch.merged": { + "pull_request.pending_failure": { "post": { - "operationId": "pull_request_batch.merged", - "summary": "Pull request batch merged", - "description": "Triggered when the last pull request in a batch gets merged", + "operationId": "pull_request.pending_failure", + "summary": "Pull request pending failure", + "description": "Triggered when a PR enters pending failure state while in the merge queue", "security": [], "requestBody": { "content": { @@ -5889,40 +8167,111 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, - "merged_reason": { + "batched": { + "type": "boolean", + "description": "Whether this pull request was part of a batch" + }, + "failure_reason": { "type": "string", "enum": [ - "MERGE_GRAPH_MERGE", - "MANUAL_MERGE", - "MERGE_GRAPH_DIRECT_MERGE" + "START_TEST_RUN_INVALID_EVENT", + "START_TEST_RUN_MERGE_CONFLICT", + "START_TEST_RUN_CONFIG_NOT_FOUND", + "START_TEST_RUN_CONFIG_PARSING_FAILURE", + "START_TEST_RUN_CONFIG_MISSING_REQUIRED_STATUSES", + "START_TEST_RUN_CONFIG_BAD_REQUIRED_STATUSES", + "START_TEST_RUN_CONFIG_BAD_VERSION", + "START_TEST_RUN_NO_REQUIRED_STATUSES", + "TEST_RUN_REQUIRED_STATUS_FAILED", + "TEST_RUN_TIMEOUT", + "GITHUB_API_MERGE_PR_FAILED", + "GITHUB_API_DIRECT_MERGE_PR_FAILED", + "GITHUB_API_RATE_LIMIT_EXCEEDED", + "PR_UPDATED_AT_MERGE_TIME", + "START_TEST_RUN_RETRY_EXHAUSTED", + "START_TEST_RUN_DRAFT_PRS_NOT_ALLOWED", + "TEST_RUN_FAILED_BY_OPTIMIZATION", + "GITHUB_API_BRANCH_PROTECTION_UNMET", + "GITHUB_API_MERGE_ALREADY_IN_PROGRESS", + "GITHUB_API_REPEATED_SERVER_ERRORS", + "START_TEST_RUN_PERMISSIONS_BLOCK_TEST_BRANCH" ], - "description": "The reason the batch was merged" + "description": "The reason the PR is pending failure" + }, + "waiting_for_prs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" + }, + "title": { + "type": "string", + "description": "The title of the PR, when known" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the PR on the source control host, when known" + } + }, + "required": [ + "pr_number" + ] + }, + "description": "The other PRs this one is currently waiting on, which differ by event: on a submitted event, the queued PRs below it in its stack that must merge first (only pr_number is known for these, so title and http_url are absent); on a queued event, the PRs ahead of it that are pending failure and could send it back to the queue; on a pending_failure event, the PRs ahead of it whose failure would fail this one. Omitted entirely when this PR is waiting on no other PR, so the key is absent rather than an empty array. Reflects the moment the event fired: a PR that starts waiting later does not re-emit the event. Distinct from related_prs, which names the PRs whose outcome has already caused this event." + }, + "failure_causing_statuses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the required status check" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the check run or status check, when GitHub reported one" + }, + "conclusion": { + "type": "string", + "description": "The conclusion GitHub reported for the check, when known" + } + }, + "required": [ + "name" + ] + }, + "description": "The required status checks that caused the test run to fail. Populated when the failure reason is TEST_RUN_REQUIRED_STATUS_FAILED, and omitted for a failure unrelated to a test run or where the failing checks were not recorded." }, "type": { "type": "string", - "const": "pull_request_batch.merged", + "const": "pull_request.pending_failure", "description": "The type of webhook event that occurred" }, "action": { "type": "string", - "const": "merged", + "const": "pending_failure", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -5949,8 +8298,12 @@ }, "status": { "type": "string", - "const": "merged", - "description": "The current status of the Pull Request batch" + "const": "pending_failure", + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -5963,37 +8316,50 @@ } }, "required": [ - "test_branch", - "test_branch_sha", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when the last pull request in a batch gets merged" + "description": "Triggered when a PR enters pending failure state while in the merge queue" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, - "merged_reason": "MERGE_GRAPH_MERGE", - "type": "pull_request_batch.merged", - "action": "merged", - "pr_numbers": [ - 0 + "batched": true, + "failure_reason": "START_TEST_RUN_INVALID_EVENT", + "waiting_for_prs": [ + { + "pr_number": 0, + "title": "string", + "http_url": "http://example.com" + } ], - "pr_numbers_in_batch": [ - 0 + "failure_causing_statuses": [ + { + "name": "string", + "http_url": "http://example.com", + "conclusion": "string" + } ], + "type": "pull_request.pending_failure", + "action": "pending_failure", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, - "status": "merged", + "status": "pending_failure", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -6003,11 +8369,11 @@ "responses": {} } }, - "pull_request_batch.queued": { + "pull_request.queued": { "post": { - "operationId": "pull_request_batch.queued", - "summary": "Pull request batch queued", - "description": "Triggered when a batch of PRs is queued", + "operationId": "pull_request.queued", + "summary": "Pull request queued", + "description": "Triggered when a PR has passed any branch protection requirements and is ready to be tested in the merge queue", "security": [], "requestBody": { "content": { @@ -6015,19 +8381,6 @@ "schema": { "type": "object", "properties": { - "test_branch": { - "type": "string", - "description": "The branch the pull request or pull request batch was tested on" - }, - "test_branch_sha": { - "type": "string", - "description": "The SHA of the branch the pull request or pull request batch was tested on" - }, - "test_pr_number": { - "type": "integer", - "minimum": 0, - "description": "The number of the pull request used to test the pull request or pull request batch" - }, "queued_reason": { "type": "string", "enum": [ @@ -6042,11 +8395,73 @@ "BISECTION_REQUIRED", "BISECTION_TEST_RUN_PASSED" ], - "description": "The reason the batch was queued" + "description": "The reason the PR was queued" + }, + "related_prs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" + }, + "title": { + "type": "string", + "description": "The title of the PR" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the PR on the source control host" + } + }, + "required": [ + "pr_number", + "title", + "http_url" + ] + }, + "description": "The other PRs in the queue whose outcome caused this event: for a queued event, the prerequisite PRs that failed, were canceled or were manually merged ahead of this one, or the skip-the-line PR that interrupted it. Carries every PR of a batch when the prerequisite failed as part of one, since a batch fails as a unit and all of its PRs failed. Omitted entirely for a reason that names no other PR, such as MERGE_ITEM_NOW_READY." + }, + "waiting_for_prs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" + }, + "title": { + "type": "string", + "description": "The title of the PR, when known" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the PR on the source control host, when known" + } + }, + "required": [ + "pr_number" + ] + }, + "description": "The other PRs this one is currently waiting on, which differ by event: on a submitted event, the queued PRs below it in its stack that must merge first (only pr_number is known for these, so title and http_url are absent); on a queued event, the PRs ahead of it that are pending failure and could send it back to the queue; on a pending_failure event, the PRs ahead of it whose failure would fail this one. Omitted entirely when this PR is waiting on no other PR, so the key is absent rather than an empty array. Reflects the moment the event fired: a PR that starts waiting later does not re-emit the event. Distinct from related_prs, which names the PRs whose outcome has already caused this event." + }, + "full_queue": { + "type": "boolean", + "description": "Whether the queue was at its concurrency limit when this PR was queued. A single reason is attributed per event, so false does not by itself mean the queue had room — a PR held behind a pending failure reports the wait in waiting_for_prs instead." + }, + "waiting_to_be_batched": { + "type": "boolean", + "description": "Whether this PR is waiting for more PRs to form a batch before testing" }, "type": { "type": "string", - "const": "pull_request_batch.queued", + "const": "pull_request.queued", "description": "The type of webhook event that occurred" }, "action": { @@ -6054,21 +8469,19 @@ "const": "queued", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -6096,7 +8509,11 @@ "status": { "type": "string", "const": "queued", - "description": "The current status of the Pull Request batch" + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -6109,37 +8526,50 @@ } }, "required": [ - "test_branch", - "test_branch_sha", + "full_queue", + "waiting_to_be_batched", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a batch of PRs is queued" + "description": "Triggered when a PR has passed any branch protection requirements and is ready to be tested in the merge queue" }, "example": { - "test_branch": "string", - "test_branch_sha": "string", - "test_pr_number": 0, "queued_reason": "MANUAL_PUSH_TO_TARGET_BRANCH", - "type": "pull_request_batch.queued", - "action": "queued", - "pr_numbers": [ - 0 + "related_prs": [ + { + "pr_number": 0, + "title": "string", + "http_url": "http://example.com" + } ], - "pr_numbers_in_batch": [ - 0 + "waiting_for_prs": [ + { + "pr_number": 0, + "title": "string", + "http_url": "http://example.com" + } ], + "full_queue": true, + "waiting_to_be_batched": true, + "type": "pull_request.queued", + "action": "queued", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "queued", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -6149,11 +8579,11 @@ "responses": {} } }, - "pull_request_batch.submitted": { + "pull_request.submitted": { "post": { - "operationId": "pull_request_batch.submitted", - "summary": "Pull request batch submitted", - "description": "Triggered when a batch of PRs is submitted", + "operationId": "pull_request.submitted", + "summary": "Pull request submitted", + "description": "Triggered when a PR is submitted to Trunk Merge", "security": [], "requestBody": { "content": { @@ -6161,19 +8591,6 @@ "schema": { "type": "object", "properties": { - "test_branch": { - "type": "string", - "description": "The branch the pull request or pull request batch was tested on" - }, - "test_branch_sha": { - "type": "string", - "description": "The SHA of the branch the pull request or pull request batch was tested on" - }, - "test_pr_number": { - "type": "integer", - "minimum": 0, - "description": "The number of the pull request used to test the pull request or pull request batch" - }, "submitted_reason": { "type": "string", "enum": [ @@ -6181,11 +8598,37 @@ "TRUNK_ADMIN_REQUESTED", "API_REQUESTED" ], - "description": "The reason the batch was submitted" + "description": "The reason the PR was submitted" + }, + "waiting_for_prs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" + }, + "title": { + "type": "string", + "description": "The title of the PR, when known" + }, + "http_url": { + "type": "string", + "format": "uri", + "description": "Web link to the PR on the source control host, when known" + } + }, + "required": [ + "pr_number" + ] + }, + "description": "The other PRs this one is currently waiting on, which differ by event: on a submitted event, the queued PRs below it in its stack that must merge first (only pr_number is known for these, so title and http_url are absent); on a queued event, the PRs ahead of it that are pending failure and could send it back to the queue; on a pending_failure event, the PRs ahead of it whose failure would fail this one. Omitted entirely when this PR is waiting on no other PR, so the key is absent rather than an empty array. Reflects the moment the event fired: a PR that starts waiting later does not re-emit the event. Distinct from related_prs, which names the PRs whose outcome has already caused this event." }, "type": { "type": "string", - "const": "pull_request_batch.submitted", + "const": "pull_request.submitted", "description": "The type of webhook event that occurred" }, "action": { @@ -6193,21 +8636,19 @@ "const": "submitted", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -6235,7 +8676,11 @@ "status": { "type": "string", "const": "submitted", - "description": "The current status of the Pull Request batch" + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -6248,37 +8693,39 @@ } }, "required": [ - "test_branch", - "test_branch_sha", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when a batch of PRs is submitted" + "description": "Triggered when a PR is submitted to Trunk Merge" }, "example": { - "test_branch": "string", - "test_branch_sha": "string", - "test_pr_number": 0, "submitted_reason": "USER_REQUESTED", - "type": "pull_request_batch.submitted", - "action": "submitted", - "pr_numbers": [ - 0 - ], - "pr_numbers_in_batch": [ - 0 + "waiting_for_prs": [ + { + "pr_number": 0, + "title": "string", + "http_url": "http://example.com" + } ], + "type": "pull_request.submitted", + "action": "submitted", + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "submitted", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" } @@ -6288,11 +8735,11 @@ "responses": {} } }, - "pull_request_batch.testing": { + "pull_request.testing": { "post": { - "operationId": "pull_request_batch.testing", - "summary": "Pull request batch testing", - "description": "Triggered when all pull requests in a batch start testing in the merge queue", + "operationId": "pull_request.testing", + "summary": "Pull request testing", + "description": "Triggered when a PR has started testing in the merge queue", "security": [], "requestBody": { "content": { @@ -6313,13 +8760,17 @@ "minimum": 0, "description": "The number of the pull request used to test the pull request or pull request batch" }, + "batched": { + "type": "boolean", + "description": "Whether this pull request was part of a batch" + }, "is_bisection": { "type": "boolean", "description": "Whether this event is part of a bisection test run" }, "type": { "type": "string", - "const": "pull_request_batch.testing", + "const": "pull_request.testing", "description": "The type of webhook event that occurred" }, "action": { @@ -6327,21 +8778,19 @@ "const": "testing", "description": "The type of action that triggered the webhook" }, - "pr_numbers": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of the pull requests in the batch" + "author": { + "type": "string", + "description": "The username of the author of the PR" }, - "pr_numbers_in_batch": { - "type": "array", - "items": { - "type": "integer", - "minimum": 0 - }, - "description": "The PR numbers of all pull requests that were tested together in this batch. This may be a superset of pr_numbers if some PRs in the batch failed to merge." + "http_details_url": { + "type": "string", + "format": "uri", + "description": "Web link to the details about this PR" + }, + "pr_number": { + "type": "integer", + "minimum": 0, + "description": "The PR number" }, "repository": { "type": "object", @@ -6369,7 +8818,11 @@ "status": { "type": "string", "const": "testing", - "description": "The current status of the Pull Request batch" + "description": "The current status of the PR" + }, + "submitter": { + "type": "string", + "description": "The username of the user who submitted the PR to the merge queue, if known" }, "target_branch": { "type": "string", @@ -6382,38 +8835,37 @@ } }, "required": [ - "test_branch", - "test_branch_sha", "is_bisection", "type", "action", - "pr_numbers", + "author", + "http_details_url", + "pr_number", "repository", "status", "target_branch", "timestamp" ], - "description": "Triggered when all pull requests in a batch start testing in the merge queue" + "description": "Triggered when a PR has started testing in the merge queue" }, "example": { "test_branch": "string", "test_branch_sha": "string", "test_pr_number": 0, + "batched": true, "is_bisection": true, - "type": "pull_request_batch.testing", + "type": "pull_request.testing", "action": "testing", - "pr_numbers": [ - 0 - ], - "pr_numbers_in_batch": [ - 0 - ], + "author": "string", + "http_details_url": "http://example.com", + "pr_number": 0, "repository": { "host": "string", "owner": "string", "name": "string" }, "status": "testing", + "submitter": "string", "target_branch": "string", "timestamp": "2019-08-24T14:15:22Z" }