Bandum API (runs on your machine): releases
Release candidates per milestone, approval and the release workflow (B3)
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/releasesRelease candidates (open milestones) and recent releases of each repo
B3 Release. Each open milestone is a candidate with a state computed from the copy Bandum has (no extra call to GitHub): empty, not_ready, ready, approved, running, failed, released. Without repo: every repo of the organization.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
repo | query | string | owner/repo |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Candidates per repo | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Repo, milestone, task or organization not found | application/problem+json · object |
Example response
{
"repos": [
{
"repo": "string",
"project": "string",
"taskSource": "scm",
"unsupported": "string",
"candidates": [],
"releases": []
}
]
}Call with curl
curl "http://localhost:8070/v1/releases" \
-H "Authorization: Bearer $BANDUM_LOCAL_KEY"/v1/releases/{owner}/{repo}/{milestone}Release candidate of a milestone, with the proposed version and generated release notes
milestone is the milestone number. Besides the state it returns each task with its reason when not ready, the proposed version (semver from labels, only when the scm kit answers), the generated release notes (grouped by type: label, in the repo language of .bandum.json), the last run, and whether the caller may approve (permission). If owner has several segments (GitLab subgroups), encode / as %2F.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
repo | path | string | yes | |
milestone | path | integer | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Candidate | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Repo, milestone, task or organization not found | application/problem+json · object |
Example response
{
"repo": "string",
"project": "string",
"milestone": {
"number": 0,
"title": "string",
"open": false
},
"state": "empty",
"counted": 0,
"reasons": [
{
"task": 0,
"code": "todo",
"detail": "string"
}
],
"tasks": [
{
"number": 0,
"key": "string",
"title": "string",
"url": "string",
"status": "string",
"type": "feature",
"closed": false
}
],
"notes": "string",
"config": {
"workflow": "string",
"recordIn": "repo",
"versionPrefix": "string",
"closeMilestone": false,
"language": "en"
},
"permission": {
"canApprove": false,
"reason": "string"
},
"supported": false
}Call with curl
curl "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>" \
-H "Authorization: Bearer $BANDUM_LOCAL_KEY"/v1/releases/{owner}/{repo}/{milestone}/approveApprove the release (writes the approval record, then runs the release workflow)
Uses the connected account of the signed-in user (local mode: the token from BANDUM_SCM_TOKEN_CMD), never the service token. Steps: check permission (online: Tara owner/admin, or releaseApprovers when set, and write access on Git), re-read the milestone and PRs, check the version (valid semver, greater than the previous tag, tag not taken), write docs/releases/<version>.md (or put the record in the Release when release.recordIn is release), then call the workflow (or create the tag and Release when the repo has no release.workflow). Two people approving at once: one wins, the other gets 409.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
repo | path | string | yes | |
milestone | path | integer | yes |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Semver | |
notes | string | yes | Release notes (Markdown) |
Responses
| Code | Description | Type |
|---|---|---|
| 201 | Approved; the run is queued (or done when there is no workflow) | application/json · object |
| 400 | Invalid parameter | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Not allowed to approve (role, release approvers, account not connected, or the account cannot write) | application/problem+json · object |
| 404 | Repo, milestone, task or organization not found | application/problem+json · object |
| 409 | Not ready any more, version taken, someone else is approving, or the default branch is protected (the detail names the two remedies) | application/problem+json · object |
| 422 | The scm kit has no release group, or the workflow could not be started (the approval record stays; fix it and retry) | application/problem+json · object |
Example response
{
"version": "string",
"tag": "string",
"state": "queued",
"commit": "string"
}Call with curl
curl -X POST "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>/approve" \
-H "Authorization: Bearer $BANDUM_LOCAL_KEY" \
-H "Content-Type: application/json" \
-d '{"version":"string","notes":"string"}'/v1/releases/{owner}/{repo}/{milestone}/retryRun the release workflow again after a failure (same version, commit and notes of the approval record)
Only when the last run failed or was cancelled and the version has no tag. Does not write the record again.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
repo | path | string | yes | |
milestone | path | integer | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The workflow was started again | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Not allowed to approve | application/problem+json · object |
| 404 | Repo, milestone, task or organization not found | application/problem+json · object |
| 409 | The last run did not fail, the tag exists, or someone else is acting on this milestone | application/problem+json · object |
| 422 | The scm kit has no release group, or the workflow could not be started | application/problem+json · object |
Example response
{
"version": "string",
"tag": "string",
"state": "queued",
"commit": "string"
}Call with curl
curl -X POST "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>/retry" \
-H "Authorization: Bearer $BANDUM_LOCAL_KEY"/v1/releases/{owner}/{repo}/{milestone}/statusLast run of the milestone, refreshed from the workflow when it is still running
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
owner | path | string | yes | |
repo | path | string | yes | |
milestone | path | integer | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Run | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Repo, milestone, task or organization not found | application/problem+json · object |
Example response
{
"version": "string",
"tag": "string",
"state": "queued",
"commit": "string"
}Call with curl
curl "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>/status" \
-H "Authorization: Bearer $BANDUM_LOCAL_KEY"