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

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

probjectoptional

Example: {"number":1}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofoptional

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

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

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/submitPullRequest' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "pr": {
      "number": 1
    },
    "targetBranch": "main",
    "priority": "medium"
  }'

200

401

200

No body

OK

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

post

Authorizations

Body

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

probjectoptional

Example: {"number":1}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

priorityone ofoptional

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

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/getSubmittedPullRequest' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "pr": {
      "number": 1
    },
    "targetBranch": "main",
    "priority": "medium"
  }'

200

401

404

200

{
  "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"
}

Information on the pull request

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

post

Authorizations

Body

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

probjectoptional

Example: {"number":1}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/restartTestsOnPullRequest' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "pr": {
      "number": 1
    },
    "targetBranch": "main"
  }'

200

401

200

No body

OK

Cancel a pull request already in the queue.

post

Authorizations

Body

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

probjectoptional

Example: {"number":1}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/cancelPullRequest' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "pr": {
      "number": 1
    },
    "targetBranch": "main"
  }'

200

401

200

No body

OK

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

post

Authorizations

Body

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/getQueue' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "targetBranch": "main"
  }'

200

401

404

200

{
  "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"
    }
  ]
}

Information on the pull request

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

repoobjectoptional

Example: {"host":"github.com","owner":"trunk-io","name":"trunk"}

probjectoptional

Example: {"number":1,"sha":"1234567890abcdef"}

targetBranchstringoptional

The branch the merge queue will be merging PRs into

Example: main

impactedTargetsone ofoptional

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

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

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.trunk.io/v1/setImpactedTargets' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": {
      "host": "github.com",
      "owner": "trunk-io",
      "name": "trunk"
    },
    "pr": {
      "number": 1,
      "sha": "1234567890abcdef"
    },
    "targetBranch": "main",
    "impactedTargets": [
      "services_backend",
      "services_frontend"
    ]
  }'

200

401

200

No body

OK