API reference

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.

Pull Request Endpoints

Cancel a pull request in a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/cancelPullRequest

HTTPcURLJavaScriptPython

POST /v1/cancelPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

Get a submitted pull request from a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

idstringOptional

statestring · enumOptionalPossible values:

stateChangedAtstringRequired

priorityValuenumberRequired

priorityNamestringRequired

usedDefaultPriorityNamestringOptional

skipTheLinebooleanRequired

isCurrentlySubmittedToQueuebooleanRequired

prNumbernumberRequired

prTitlestringRequired

prShastringRequired

prBaseBranchstringRequired

prAuthorstringRequired

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getSubmittedPullRequest

HTTPcURLJavaScriptPython

POST /v1/getSubmittedPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

{
  "id": "text",
  "state": "NOT_READY",
  "readiness": {
    "hasImpactedTargets": true,
    "requiresImpactedTargets": true,
    "doesBaseBranchMatch": true,
    "gitHubMergeability": "UNSPECIFIED"
  },
  "stateChangedAt": "text",
  "priorityValue": 1,
  "priorityName": "text",
  "usedDefaultPriorityName": "text",
  "skipTheLine": true,
  "isCurrentlySubmittedToQueue": true,
  "prNumber": 1,
  "prTitle": "text",
  "prSha": "text",
  "prBaseBranch": "text",
  "prAuthor": "text"
}

Restart tests on a pull request in a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/restartTestsOnPullRequest

HTTPcURLJavaScriptPython

POST /v1/restartTestsOnPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text"
}

Set impacted targets for a pull request.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

impactedTargetsany ofRequired

string[]Optional

or

const: ALLOptional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/setImpactedTargets

HTTPcURLJavaScriptPython

POST /v1/setImpactedTargets HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1,
    "sha": "text"
  },
  "targetBranch": "text",
  "impactedTargets": [
    "text"
  ]
}

Submit a pull request to a merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

priorityany ofOptional

integer · max: 4294967295Optional

or

stringOptional

or

nullOptional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/submitPullRequest

HTTPcURLJavaScriptPython

POST /v1/submitPullRequest HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "text",
  "priority": 1
}

Get details about testing that Merge Queue is performing

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

testRunIdstringRequired

targetBranchstringRequired

Responses

200

OK

application/json

requiredStatusesstring[]Required

requiredStatusesSourcestring · enumOptionalPossible values:

testBranchstringRequired

testBranchShastringRequired

createdAtstringOptional

statusstring · enumOptionalPossible values:

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getMergeQueueTestingDetails

HTTPcURLJavaScriptPython

POST /v1/getMergeQueueTestingDetails HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "testRunId": "text",
  "targetBranch": "text"
}

{
  "requiredStatuses": [
    "text"
  ],
  "requiredStatusesSource": "TRUNK_CONFIG",
  "testBranch": "text",
  "testBranchSha": "text",
  "createdAt": "text",
  "status": "IN_PROGRESS",
  "checkSuites": [
    {
      "checkRuns": [
        {
          "name": "text",
          "url": "text",
          "status": "QUEUED",
          "conclusion": "ACTION_REQUIRED"
        }
      ]
    }
  ],
  "statusChecks": [
    {
      "context": "text",
      "url": "text",
      "state": "ERROR"
    }
  ],
  "testedPullRequests": [
    {
      "prNumber": 1,
      "prUrl": "text",
      "title": "text"
    }
  ]
}

Queue Endpoints

Create a new merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

modestring · enumOptionalPossible values:

concurrencyinteger · min: 1 · max: 4294967295Optional

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/createQueue

HTTPcURLJavaScriptPython

POST /v1/createQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text",
  "mode": "single",
  "concurrency": 1
}

Delete the specified merge queue. The queue must be empty in order to be deleted.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/deleteQueue

HTTPcURLJavaScriptPython

POST /v1/deleteQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text"
}

Get the merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

Responses

200

OK

application/json

statestring · enumOptionalPossible values:

branchstringRequired

concurrencynumberRequired

testingTimeoutMinsnumberRequired

modestring · enumOptionalPossible values:

canOptimisticallyMergebooleanRequired

pendingFailureDepthnumberRequired

isBatchingbooleanRequired

batchingMaxWaitTimeMinsnumberRequired

batchingMinSizenumberRequired

createPrsForTestingBranchesbooleanRequired

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/getQueue

HTTPcURLJavaScriptPython

POST /v1/getQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text"
}

{
  "state": "RUNNING",
  "branch": "text",
  "concurrency": 1,
  "testingTimeoutMins": 1,
  "mode": "SINGLE",
  "canOptimisticallyMerge": true,
  "pendingFailureDepth": 1,
  "isBatching": true,
  "batchingMaxWaitTimeMins": 1,
  "batchingMinSize": 1,
  "createPrsForTestingBranches": true,
  "enqueuedPullRequests": [
    {
      "id": "text",
      "state": "NOT_READY",
      "stateChangedAt": "text",
      "priorityValue": 1,
      "priorityName": "text",
      "usedDefaultPriorityName": "text",
      "skipTheLine": true,
      "prNumber": 1,
      "prTitle": "text",
      "prSha": "text",
      "prBaseBranch": "text",
      "prAuthor": "text"
    }
  ]
}

Update the merge queue.

post

Authorizations

ApiKeyAuth

x-api-tokenstringRequired

Body

application/json

targetBranchstringRequired

The branch that the merge queue is targeting.

statestring · enumOptional

The desired state of the merge queue. Valid values: RUNNING, PAUSED, DRAINING.

Possible values:

concurrencyinteger · min: 1 · max: 4294967295Optional

The number of PRs or batches of PRs the queue can test at once.

bisectionConcurrencyinteger · min: 1 · max: 4294967295Optional

The number of tests the merge queue can run when bisecting a batch to figure out what PR in the batch failed.

testingTimeoutMinutesinteger · min: 1 · max: 4294967295Optional

The maximum number of minutes the merge queue will wait for tests to complete before timing out.

pendingFailureDepthinteger · min: 1 · max: 4294967295Optional

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.

canOptimisticallyMergebooleanOptional

When enabled, a PR that passes tests will also cause any PR ahead of it in the queue to also get marked as passing, since tests have passed with those commits.

batchbooleanOptional

Enable or disable batching. When enabled, the merge queue will group PRs into batches for testing.

batchingMaxWaitTimeMinutesinteger · min: 1 · max: 4294967295Optional

The maximum number of minutes the merge queue will wait to collect PRs into a batch before starting tests.

batchingMinSizeinteger · min: 1 · max: 4294967295Optional

The minimum number of PRs required to form a batch.

modestring · enumOptional

The queue mode. 'single' processes PRs one at a time. 'parallel' processes multiple PRs concurrently.

Possible values:

commentsEnabledbooleanOptional

Whether or not Merge Queue will post GitHub comments on PRs.

commandsEnabledbooleanOptional

Whether or not users are allowed to submit PRs to the merge queue by commenting /trunk merge.

createPrsForTestingBranchesbooleanOptional

Whether or not the merge queue will create PRs for its testing branches, allowing CI to run on them.

directMergeModestring · enumOptional

Allow PRs to merge directly into the target branch if they're up to date with the target branch when submitting them to the queue instead of running tests on them in the merge queue.

Possible values:

optimizationModestring · enumOptional

The optimization strategy for the merge queue. 'OFF' disables optimizations. 'BISECTION_SKIP_REDUNDANT_TESTS' uses bisection and skips redundant tests.

Possible values:

mergeMethodstring · enumOptional

The Git merge method used when merging PRs into the target branch. Valid values: MERGE_COMMIT, SQUASH, REBASE.

Possible values:

statusCheckEnabledbooleanOptional

Post a GitHub status check on PRs with the status of the PR in the merge queue.

requiredStatusesstring[]Optional

Allows setting the statuses that must pass when the merge queue performs tests in order for a PR to merge. Setting the statuses here will override GitHub branch protection settings or your .trunk/trunk.yaml.

deleteRequiredStatusesbooleanOptional

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.

Responses

200

OK

application/json

400

Bad Request

application/plain-text

401

Unauthorized

application/plain-text

404

Not Found

application/plain-text

500

Internal Server Error

application/plain-text

post

/updateQueue

HTTPcURLJavaScriptPython

POST /v1/updateQueue HTTP/1.1
Host: api.trunk.io
x-api-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 537

{
  "repo": {
    "host": "text",
    "owner": "text",
    "name": "text"
  },
  "targetBranch": "text",
  "state": "RUNNING",
  "concurrency": 1,
  "bisectionConcurrency": 1,
  "testingTimeoutMinutes": 1,
  "pendingFailureDepth": 1,
  "canOptimisticallyMerge": true,
  "batch": true,
  "batchingMaxWaitTimeMinutes": 1,
  "batchingMinSize": 1,
  "mode": "single",
  "commentsEnabled": true,
  "commandsEnabled": true,
  "createPrsForTestingBranches": true,
  "directMergeMode": "OFF",
  "optimizationMode": "OFF",
  "mergeMethod": "MERGE_COMMIT",
  "statusCheckEnabled": true,
  "requiredStatuses": [
    "text"
  ],
  "deleteRequiredStatuses": true
}