mergeapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Trunk Merge API",
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "https://api.trunk.io/v1",
      "description": "Server description"
    }
  ],
  "components": {
    "securitySchemes": {
      "x-api-token": {
        "name": "x-api-token",
        "type": "apiKey",
        "in": "header",
        "description": "Trunk API token - see https://docs.trunk.io/apis#authentication"
      }
    },
    "schemas": {
      "repo": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "example": "github.com",
            "description": "The host of the repository. Currently only supports 'github.com'",
            "enum": [
              "github.com"
            ]
          },
          "owner": {
            "type": "string",
            "example": "trunk-io",
            "description": "The owner of the repository"
          },
          "name": {
            "type": "string",
            "example": "trunk",
            "description": "The name of the repository"
          }
        },
        "example": {
          "host": "github.com",
          "owner": "trunk-io",
          "name": "trunk"
        }
      },
      "pr": {
        "type": "object",
        "properties": {
          "number": {
            "type": "number",
            "example": 1,
            "description": "The PR number"
          }
        },
        "example": {
          "number": 1
        }
      },
      "prWithSha": {
        "type": "object",
        "properties": {
          "number": {
            "type": "number",
            "example": 1,
            "description": "The PR number"
          },
          "sha": {
            "type": "string",
            "example": "1234567890abcdef",
            "description": "The SHA of the PR"
          }
        },
        "example": {
          "number": 1,
          "sha": "1234567890abcdef"
        }
      },
      "targetBranch": {
        "type": "string",
        "example": "main",
        "description": "The branch the merge queue will be merging PRs into"
      },
      "prReadiness": {
        "type": "object",
        "properties": {
          "hasImpactedTargets": {
            "type": "boolean",
            "example": false,
            "description": "Whether the PR has had impacted targets uploaded for it"
          },
          "requiresImpactedTargets": {
            "type": "boolean",
            "example": false,
            "description": "Whether the PR requires impacted targets to be uploaded for it before moving into the queue. This is true if the queue is in parallel mode"
          },
          "doesBaseBranchMatch": {
            "type": "boolean",
            "example": true,
            "description": "Whether the base branch of the PR matches the target branch of the queue"
          },
          "gitHubMergeability": {
            "type": "string",
            "enum": [
              "MERGEABLE",
              "NOT_MERGEABLE",
              "IN_PROGRESS",
              "UNSPECIFIED"
            ],
            "example": "MERGEABLE",
            "description": "The mergeability status of the PR on GitHub"
          }
        },
        "example": {
          "hasImpactedTargets": false,
          "requiresImpactedTargets": false,
          "doesBaseBranchMatch": true,
          "gitHubMergeability": "MERGEABLE"
        }
      },
      "pullRequest": {
        "type": "object",
        "properties": {
          "number": {
            "type": "number",
            "example": 1,
            "description": "The PR number"
          },
          "title": {
            "type": "string",
            "example": "Add new feature",
            "description": "The title of the PR"
          },
          "sha": {
            "type": "string",
            "example": "1234567890abcdef",
            "description": "The head SHA of the PR"
          },
          "baseBranch": {
            "type": "string",
            "example": "main",
            "description": "The base branch of the PR"
          },
          "author": {
            "type": "string",
            "example": "dependabot",
            "description": "The author of the PR"
          }
        },
        "example": {
          "number": 1,
          "title": "Add new feature",
          "sha": "1234567890abcdef",
          "baseBranch": "main",
          "author": "dependabot"
        }
      },
      "mergeItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the merge item in the queue"
          },
          "state": {
            "type": "string",
            "enum": [
              "NOT_READY",
              "PENDING",
              "TESTING",
              "TESTS_PASSED",
              "PENDING_FAILURE",
              "FAILED",
              "CANCELLED",
              "MERGED"
            ],
            "description": "The state of the PR in the queue - see https://docs.trunk.io/merge/reference#pr-states"
          },
          "stateChangedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The time the state of the PR changed"
          },
          "priorityValue": {
            "type": "number",
            "example": 100,
            "description": "The priority value of the PR in the queue - ranges from 0-255 with 0 being the highest"
          },
          "priorityName": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ],
            "example": "medium",
            "description": "The priority name of the PR in the queue. Defaults to medium"
          },
          "usedDefaultPriorityName": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ],
            "example": "medium",
            "description": "The default priority given to the PR if no explicit priority was specified"
          },
          "skipTheLine": {
            "type": "boolean",
            "example": false,
            "description": "Whether the PR will skip the line of the queue"
          },
          "isCurrentlySubmittedToQueue": {
            "type": "boolean",
            "description": "Whether the PR is currently submitted to the queue."
          },
          "readiness": {
            "$ref": "#/components/schemas/prReadiness"
          },
          "prNumber": {
            "type": "number",
            "example": 1,
            "description": "The PR number"
          },
          "prTitle": {
            "type": "string",
            "example": "Add new feature",
            "description": "The title of the PR"
          },
          "prSha": {
            "type": "string",
            "example": "1234567890abcdef",
            "description": "The head SHA of the PR"
          },
          "prBaseBranch": {
            "type": "string",
            "example": "main",
            "description": "The base branch of the PR"
          },
          "prAuthor": {
            "type": "string",
            "example": "dependabot",
            "description": "The author of the PR"
          }
        },
        "example": {
          "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"
        }
      },
      "mergeItemWithoutReadiness": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the merge item in the queue"
          },
          "state": {
            "type": "string",
            "enum": [
              "NOT_READY",
              "PENDING",
              "TESTING",
              "TESTS_PASSED",
              "PENDING_FAILURE",
              "FAILED",
              "CANCELLED",
              "MERGED"
            ],
            "description": "The state of the PR in the queue - see https://docs.trunk.io/merge/reference#pr-states"
          },
          "stateChangedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The time the state of the PR changed"
          },
          "priorityValue": {
            "type": "number",
            "example": 100,
            "description": "The priority value of the PR in the queue - ranges from 0-255 with 0 being the highest"
          },
          "priorityName": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ],
            "example": "medium",
            "description": "The priority name of the PR in the queue. Defaults to medium"
          },
          "usedDefaultPriorityName": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ],
            "example": "medium",
            "description": "The default priority given to the PR if no explicit priority was specified"
          },
          "skipTheLine": {
            "type": "boolean",
            "example": false,
            "description": "Whether the PR will skip the line of the queue"
          },
          "prNumber": {
            "type": "number",
            "example": 1,
            "description": "The PR number"
          },
          "prTitle": {
            "type": "string",
            "example": "Add new feature",
            "description": "The title of the PR"
          },
          "prSha": {
            "type": "string",
            "example": "1234567890abcdef",
            "description": "The head SHA of the PR"
          },
          "prBaseBranch": {
            "type": "string",
            "example": "main",
            "description": "The base branch of the PR"
          },
          "prAuthor": {
            "type": "string",
            "example": "dependabot",
            "description": "The author of the PR"
          }
        },
        "example": {
          "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"
        }
      },
      "queue": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "RUNNING",
              "PAUSED",
              "DRAINING",
              "SWITCHING_MODES"
            ],
            "example": "RUNNING",
            "description": "The current state of the queue - see https://docs.trunk.io/merge-queue/set-up-trunk-merge/advanced-settings#merge-queue-states"
          },
          "branch": {
            "type": "string",
            "example": "main",
            "description": "The branch the merge queue is merging PRs into"
          },
          "concurrency": {
            "type": "number",
            "example": 1,
            "description": "The number of PRs that can be tested at the same time"
          },
          "testingTimeoutMins": {
            "type": "number",
            "example": 60,
            "description": "The number of minutes a PR can be testing before it is marked as PENDING_FAILURE"
          },
          "mode": {
            "type": "string",
            "enum": [
              "SINGLE",
              "PARALLEL"
            ],
            "description": "The mode the queue is in - see https://docs.trunk.io/merge-queue/parallel-queues",
            "example": "SINGLE"
          },
          "canOptimisticallyMerge": {
            "type": "boolean",
            "example": true,
            "description": "Whether the queue can optimistically merge PRs if one further down the queue passes tests"
          },
          "pendingFailureDepth": {
            "type": "number",
            "example": 1,
            "description": "The number of PRs that must complete testing behind a failed PR before marking the failed PR as FAILED"
          },
          "batchingMode": {
            "type": "string",
            "enum": [
              "NONE",
              "SPECULATIVE"
            ],
            "description": "The batching mode the queue is in. SPECULATIVE means batching is active. See https://docs.trunk.io/merge-queue/batching",
            "example": "SPECULATIVE"
          },
          "batchingMaxWaitTimeMins": {
            "type": "number",
            "example": 60,
            "description": "The maximum time a PR can wait in the queue before being batched"
          },
          "batchingMinSize": {
            "type": "number",
            "example": 1,
            "description": "The minimum number of PRs that must be dependent on each other before they are put into a batch"
          },
          "createPrsForTestingBranches": {
            "type": "boolean",
            "example": true,
            "description": "Whether the queue will create PRs for testing branches as opposed to just making a branch"
          },
          "enqueuedPullRequests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/mergeItemWithoutReadiness"
            }
          }
        },
        "example": {
          "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"
            }
          ]
        }
      },
      "priority": {
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ],
            "default": "medium",
            "description": "The priority name to assign to the PR when it begins testing in the queue",
            "example": "high"
          },
          {
            "type": "number",
            "example": 1,
            "description": "The priority number (0 - 255, 0 is the highest) to assign to the PR when it begins testing in the queue"
          }
        ]
      }
    }
  },
  "paths": {
    "/submitPullRequest": {
      "post": {
        "tags": [
          "Merge Items"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Submit a pull request to be tested and merged",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/pr"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  },
                  "priority": {
                    "$ref": "#/components/schemas/priority"
                  }
                },
                "example": {
                  "repo": {
                    "host": "github.com",
                    "owner": "trunk-io",
                    "name": "trunk"
                  },
                  "pr": {
                    "number": 1
                  },
                  "targetBranch": "main",
                  "priority": "medium"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/setImpactedTargets": {
      "post": {
        "tags": [
          "Impacted Targets"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Set impacted targets",
        "description": "Upload impacted targets for the PR and its current SHA. Used specifically when running the queue in Parallel mode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/prWithSha"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  },
                  "impactedTargets": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "example": "services_backend",
                          "description": "Name of the target impacted by the changes in the pull request"
                        }
                      },
                      {
                        "type": "string",
                        "enum": [
                          "IMPACTS_ALL"
                        ],
                        "description": "Special value to indicate that all targets are impacted by the changes in the pull request"
                      }
                    ]
                  }
                },
                "example": {
                  "repo": {
                    "host": "github.com",
                    "owner": "trunk-io",
                    "name": "trunk"
                  },
                  "pr": {
                    "number": 1,
                    "sha": "1234567890abcdef"
                  },
                  "targetBranch": "main",
                  "impactedTargets": [
                    "services_backend",
                    "services_frontend"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/queuePullRequest": {
      "post": {
        "tags": [
          "Merge Items"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Submits a Pull Request to the queue",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/pr"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  },
                  "priority": {
                    "$ref": "#/components/schemas/priority"
                  }
                },
                "example": {
                  "repo": {
                    "host": "github.com",
                    "owner": "trunk-io",
                    "name": "trunk"
                  },
                  "pr": {
                    "number": 1
                  },
                  "targetBranch": "main",
                  "priority": "medium"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/restartTestsOnPullRequest": {
      "post": {
        "tags": [
          "Merge Items"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Restarts tests on a PR in the queue without moving its position or causing other PRs to be retested",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/pr"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  }
                }
              },
              "example": {
                "repo": {
                  "host": "github.com",
                  "owner": "trunk-io",
                  "name": "trunk"
                },
                "pr": {
                  "number": 1
                },
                "targetBranch": "main"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/cancelPullRequest": {
      "post": {
        "tags": [
          "Merge Items"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Cancel a pull request already in the queue.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/pr"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  }
                }
              },
              "example": {
                "repo": {
                  "host": "github.com",
                  "owner": "trunk-io",
                  "name": "trunk"
                },
                "pr": {
                  "number": 1
                },
                "targetBranch": "main"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/getSubmittedPullRequest": {
      "post": {
        "tags": [
          "Merge Items"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Get information on a pull request that has been submitted to the queue",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "pr": {
                    "$ref": "#/components/schemas/pr"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  },
                  "priority": {
                    "$ref": "#/components/schemas/priority"
                  }
                },
                "example": {
                  "repo": {
                    "host": "github.com",
                    "owner": "trunk-io",
                    "name": "trunk"
                  },
                  "pr": {
                    "number": 1
                  },
                  "targetBranch": "main",
                  "priority": "medium"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Information on the pull request",
            "content": {
              "application/json": {
                "schema": {
                    "type": "object",
                    "$ref": "#/components/schemas/mergeItem"
                },
                "example": {
                  "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"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Pull request with the provided number does not exist or has never been submitted to the specified queue before"
          }
        }
      }
    },
    "/getQueue": {
      "post": {
        "tags": [
          "Merge Queue"
        ],
        "security": [
          {
            "x-api-token": []
          }
        ],
        "summary": "Get information on your merge queue and the PRs currently in it",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "$ref": "#/components/schemas/repo"
                  },
                  "targetBranch": {
                    "$ref": "#/components/schemas/targetBranch"
                  }
                }
              },
              "example": {
                "repo": {
                  "host": "github.com",
                  "owner": "trunk-io",
                  "name": "trunk"
                },
                "targetBranch": "main"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Information on the pull request",
            "content": {
              "application/json": {
                "schema": {
                    "type": "object",
                    "$ref": "#/components/schemas/queue"
                },
                "example": {
                  "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"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Pull request with the provided number does not exist or has never been submitted to the specified queue before"
          }
        }
      }
    }
  }
}