Skip to content

Bandum API (runs on your machine): releases ​

Release candidates per milestone, approval and the release workflow (B3)

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/releases

Release 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 ​

NameInTypeRequiredDescription
repoquerystringowner/repo

Responses ​

CodeDescriptionType
200Candidates per repoapplication/json · object
401Not signed inapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "repos": [
    {
      "repo": "string",
      "project": "string",
      "taskSource": "scm",
      "unsupported": "string",
      "candidates": [],
      "releases": []
    }
  ]
}

Call with curl ​

bash
curl "http://localhost:8070/v1/releases" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
GET/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 ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
milestonepathintegeryes

Responses ​

CodeDescriptionType
200Candidateapplication/json · object
401Not signed inapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "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 ​

bash
curl "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
POST/v1/releases/{owner}/{repo}/{milestone}/approve

Approve 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 ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
milestonepathintegeryes

Body (application/json) ​

FieldTypeRequiredDescription
versionstringSemver
notesstringyesRelease notes (Markdown)

Responses ​

CodeDescriptionType
201Approved; the run is queued (or done when there is no workflow)application/json · object
400Invalid parameterapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not allowed to approve (role, release approvers, account not connected, or the account cannot write)application/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object
409Not 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
422The 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 ​

json
{
  "version": "string",
  "tag": "string",
  "state": "queued",
  "commit": "string"
}

Call with curl ​

bash
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"}'
POST/v1/releases/{owner}/{repo}/{milestone}/retry

Run 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 ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
milestonepathintegeryes

Responses ​

CodeDescriptionType
200The workflow was started againapplication/json · object
401Not signed inapplication/problem+json · object
403Not allowed to approveapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object
409The last run did not fail, the tag exists, or someone else is acting on this milestoneapplication/problem+json · object
422The scm kit has no release group, or the workflow could not be startedapplication/problem+json · object

Example response ​

json
{
  "version": "string",
  "tag": "string",
  "state": "queued",
  "commit": "string"
}

Call with curl ​

bash
curl -X POST "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>/retry" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
GET/v1/releases/{owner}/{repo}/{milestone}/status

Last run of the milestone, refreshed from the workflow when it is still running

Parameters ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
milestonepathintegeryes

Responses ​

CodeDescriptionType
200Runapplication/json · object
401Not signed inapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "version": "string",
  "tag": "string",
  "state": "queued",
  "commit": "string"
}

Call with curl ​

bash
curl "http://localhost:8070/v1/releases/<owner>/<repo>/<milestone>/status" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"