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

post

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofOptional

string · enumOptional

The priority name to assign to the PR when it begins testing in the queue

Default: mediumExample: highPossible values:

or

numberOptional

The priority number (0 - 255, 0 is the highest) to assign to the PR when it begins testing in the queue

Example: 1

Responses

200

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main",
  "priority": "medium"
}

No content

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

post

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofOptional

string · enumOptional

The priority name to assign to the PR when it begins testing in the queue

Default: mediumExample: highPossible values:

or

numberOptional

The priority number (0 - 255, 0 is the highest) to assign to the PR when it begins testing in the queue

Example: 1

Responses

200

Information on the pull request

application/json

401

Unauthorized

404

Pull request with the provided number does not exist or has never been submitted to the specified queue before

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main",
  "priority": "medium"
}

{
  "id": "1234567890abcdef",
  "state": "PENDING",
  "stateChangedAt": "2021-01-01T00:00:00Z",
  "priorityValue": 100,
  "priorityName": "medium",
  "usedDefaultPriorityName": "medium",
  "skipTheLine": false,
  "isCurrentlySubmittedToQueue": true,
  "readiness": {
    "hasImpactedTargets": false,
    "requiresImpactedTargets": false,
    "doesBaseBranchMatch": true,
    "gitHubMergeability": "MERGEABLE"
  },
  "prNumber": 1,
  "prTitle": "Add new feature",
  "prSha": "1234567890abcdef",
  "prBaseBranch": "main",
  "prAuthor": "dependabot"
}

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

post

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main"
}

No content

Cancel a pull request already in the queue.

post

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1
  },
  "targetBranch": "main"
}

No content

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

post

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

Responses

200

Information on the pull request

application/json

401

Unauthorized

404

Pull request with the provided number does not exist or has never been submitted to the specified queue before

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "targetBranch": "main"
}

{
  "state": "RUNNING",
  "branch": "main",
  "concurrency": 1,
  "testingTimeoutMins": 60,
  "mode": "SINGLE",
  "canOptimisticallyMerge": true,
  "pendingFailureDepth": 1,
  "batchingMode": "SPECULATIVE",
  "batchingMaxWaitTimeMins": 60,
  "batchingMinSize": 1,
  "createPrsForTestingBranches": true,
  "enqueuedPullRequests": [
    {
      "id": "1234567890abcdef",
      "state": "PENDING",
      "stateChangedAt": "2021-01-01T00:00:00Z",
      "priorityValue": 100,
      "priorityName": "medium",
      "usedDefaultPriorityName": "medium",
      "skipTheLine": false,
      "prNumber": 1,
      "prTitle": "Add new feature",
      "prSha": "1234567890abcdef",
      "prBaseBranch": "main",
      "prAuthor": "dependabot"
    }
  ]
}

Set impacted targets

post

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

Authorizations

Body

targetBranchstringOptional

The branch the merge queue will be merging PRs into

Example: main

impactedTargetsone ofOptional

string[]Optional

Name of the target impacted by the changes in the pull request

Example: services_backend

or

string · enumOptional

Special value to indicate that all targets are impacted by the changes in the pull request

Possible values:

Responses

200

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

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

{
  "repo": {
    "host": "github.com",
    "owner": "trunk-io",
    "name": "trunk"
  },
  "pr": {
    "number": 1,
    "sha": "1234567890abcdef"
  },
  "targetBranch": "main",
  "impactedTargets": [
    "services_backend",
    "services_frontend"
  ]
}

No content