Merge Queue

Public Trunk Merge Queue API. All requests should be authenticated.

The Trunk Merge Queue API provides access to submit PRs for testing and merging, canceling PRs, and providing extra information to optimize the queue. The API is an HTTP REST API, returns JSON from all requests, and uses standard HTTP response codes.

All requests must be authenticated by providing the x-api-token header.

Submit a pull request to be tested and merged

POSThttps://api.trunk.io:433/v1/submitPullRequest

Body

application/json

reporepo (object)

prpr (object)

targetBranchtargetBranch (string)

The branch the merge queue will be merging PRs into

Example: "main"

priorityone of

enumnumber

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/submitPullRequest', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Submits a Pull Request to the queue

POSThttps://api.trunk.io:433/v1/queuePullRequest

Body

application/json

reporepo (object)

prpr (object)

targetBranchtargetBranch (string)

The branch the merge queue will be merging PRs into

Example: "main"

priorityone of

enumnumber

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/queuePullRequest', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Restarts tests on a PR in the queue without moving its position or causing other PRs to be retested

POSThttps://api.trunk.io:433/v1/restartTestsOnPullRequest

Body

application/json

reporepo (object)

prpr (object)

targetBranchtargetBranch (string)

The branch the merge queue will be merging PRs into

Example: "main"

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/restartTestsOnPullRequest', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Cancel a pull request already in the queue.

POSThttps://api.trunk.io:433/v1/cancelPullRequest

Body

application/json

reporepo (object)

prpr (object)

targetBranchtargetBranch (string)

The branch the merge queue will be merging PRs into

Example: "main"

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/cancelPullRequest', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Get information on your merge queue and the PRs currently in it

POSThttps://api.trunk.io:433/v1/getQueue

Path parameters

owner*string

owning organization of the repo the merge queue is for

Example: "trunk-io"

name*string

name of the repo the merge queue is for

Example: "trunk"

targetBranch*string

The branch the merge queue is merging PRs into

Example: "main"

Response

200401404

Information on the pull request

Body

application/json

stateenum

RUNNINGPAUSEDDRAININGSWITCHING_MODES

branchstring

The branch the merge queue is merging PRs into

Example: "main"

concurrencynumber

The number of PRs that can be tested at the same time

Example: 1

testingTimeoutMinsnumber

The number of minutes a PR can be testing before it is marked as PENDING_FAILURE

Example: 60

modeenum

The mode the queue is in

SINGLEPARALLEL

canOptimisticallyMergeboolean

Whether the queue can optimistically merge PRs if one further down the queue passes tests

Example: true

pendingFailureDepthnumber

The number of PRs that must complete testing behind a failed PR before marking the failed PR as FAILED

Example: 1

batchingModeenum

The batching mode the queue is in

NONESPECULATIVE

batchingMaxWaitTimeMinsnumber

The maximum time a PR can wait in the queue before being batched

Example: 60

batchingMinSizenumber

The minimum number of PRs that must be dependent on each other before they are put into a batch

Example: 1

createPrsForTestingBranchesboolean

Whether the queue will create PRs for testing branches as opposed to just making a branch

Example: true

enqueuedPullRequestsarray of mergeItemWithoutReadiness (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/getQueue', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

200

{
  "state": "RUNNING",
  "branch": "main",
  "concurrency": 1,
  "testingTimeoutMins": 60,
  "mode": "SINGLE",
  "canOptimisticallyMerge": true,
  "pendingFailureDepth": 1,
  "batchingMode": "NONE",
  "batchingMaxWaitTimeMins": 60,
  "batchingMinSize": 1,
  "createPrsForTestingBranches": true,
  "enqueuedPullRequests": [
    {
      "id": "text",
      "state": "NOT_READY",
      "stateChangedAt": "2024-12-21T12:31:27.836Z",
      "priorityValue": 100,
      "priorityName": "medium",
      "usedDefaultPriorityName": "medium",
      "skipTheLine": false,
      "prNumber": 1,
      "prTitle": "Add new feature",
      "prSha": "1234567890abcdef",
      "prBaseBranch": "main",
      "prAuthor": "dependabot"
    }
  ]
}

Get information on a pull request that has been submitted to the queue

POSThttps://api.trunk.io:433/v1/getSubmittedPullRequest

Path parameters

owner*string

owning organization of the repo the merge queue is for

Example: "trunk-io"

name*string

name of the repo the merge queue is for

Example: "trunk"

targetBranch*string

The branch the merge queue is merging PRs into

Example: "main"

prNumber*number

The number of the PR to get information on

Example: 1

Response

200401404

Information on the pull request

Body

application/json

idstring

The ID of the merge item in the queue

stateenum

The state of the PR in the queue - see https://docs.trunk.io/merge/reference#pr-states

NOT_READYPENDINGTESTINGTESTS_PASSEDPENDING_FAILUREFAILEDCANCELLEDMERGED

stateChangedAtstring (date-time)

The time the state of the PR changed

priorityValuenumber

The priority value of the PR in the queue - ranges from 0-255 with 0 being the highest

Example: 100

priorityNameenum

The priority name of the PR in the queue. Defaults to medium

Example: "medium"

lowmediumhighurgent

usedDefaultPriorityNameenum

The default priority given to the PR if no explicit priority was specified

Example: "medium"

lowmediumhighurgent

skipTheLineboolean

Whether the PR will skip the line of the queue

Example: false

isCurrentlySubmittedToQueueboolean

Whether the PR is currently submitted to the queue.

readinessprReadiness (object)

prNumbernumber

The PR number

Example: 1

prTitlestring

The title of the PR

Example: "Add new feature"

prShastring

The head SHA of the PR

Example: "1234567890abcdef"

prBaseBranchstring

The base branch of the PR

Example: "main"

prAuthorstring

The author of the PR

Example: "dependabot"

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/getSubmittedPullRequest', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "text",
  "state": "NOT_READY",
  "stateChangedAt": "2024-12-21T12:31:27.836Z",
  "priorityValue": 100,
  "priorityName": "medium",
  "usedDefaultPriorityName": "medium",
  "skipTheLine": false,
  "isCurrentlySubmittedToQueue": false,
  "readiness": {
    "hasImpactedTargets": false,
    "requiresImpactedTargets": false,
    "doesBaseBranchMatch": true,
    "gitHubMergeability": "MERGEABLE"
  },
  "prNumber": 1,
  "prTitle": "Add new feature",
  "prSha": "1234567890abcdef",
  "prBaseBranch": "main",
  "prAuthor": "dependabot"
}

Set impacted targets

Upload impacted targets for the PR and its current SHA. Used specifically when running the queue in Parallel mode

POSThttps://api.trunk.io:433/v1/setImpactedTargets

Body

application/json

reporepo (object)

prprWithSha (object)

targetBranchtargetBranch (string)

The branch the merge queue will be merging PRs into

Example: "main"

impactedTargetsone of

array of stringenum

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('https://api.trunk.io:433/v1/setImpactedTargets', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();