| 1 | --- |
| 2 | title: Releases |
| 3 | description: Publish a tag with a title and notes, keep drafts and pre-releases, and read the latest release from the API. |
| 4 | --- |
| 5 | |
| 6 | A release is a tag published with a title and notes, for people to see what |
| 7 | changed and download it. A repository's releases are at |
| 8 | `g1t.sh/<workspace>/<repo>/releases`, and the latest one is in the **About** |
| 9 | beside its files. |
| 10 | |
| 11 | ## Publish a release |
| 12 | |
| 13 | You need the Write role on the repository. |
| 14 | |
| 15 | 1. Open the repository's **Code → Releases**, or choose **Create a new |
| 16 | release** under **Releases** in the About beside its files. |
| 17 | 2. Choose **Draft a new release**. |
| 18 | 3. Under **Tag**, pick an existing tag or type a new one, such as `v1.2.0`. |
| 19 | 4. For a new tag, under **Target**, choose the branch or commit to make it |
| 20 | at. The default branch is used when you leave it empty. |
| 21 | 5. Give it a **Title** and **Notes** in Markdown. |
| 22 | 6. Choose **Publish release**, or **Save draft** to finish it later. |
| 23 | |
| 24 | A tag that does not exist yet is made as a lightweight tag at the target, |
| 25 | under the repository's [tag rulesets](/guides/rules/). A tag that exists is |
| 26 | released as it is. Each tag has at most one release. |
| 27 | |
| 28 | | Field | Rules | |
| 29 | | --- | --- | |
| 30 | | Tag | A valid git ref name. Required. | |
| 31 | | Target | A branch or commit. Used only for a new tag. | |
| 32 | | Title | Up to 200 characters. The tag's name is shown when it has none. | |
| 33 | | Notes | Markdown, up to 125,000 characters. | |
| 34 | | Pre-release | Not ready for everyone: it is never the latest release. | |
| 35 | |
| 36 | ## Drafts, pre-releases and the latest release |
| 37 | |
| 38 | | State | Who sees it | Latest? | |
| 39 | | --- | --- | --- | |
| 40 | | Draft | People with the Write role | Never | |
| 41 | | Pre-release | Everyone who can read the repository | Never | |
| 42 | | Published | Everyone who can read the repository | When it is the newest | |
| 43 | |
| 44 | The **latest release** is the newest published release that is neither a |
| 45 | draft nor a pre-release. To publish a draft, open it and choose **Publish |
| 46 | release**. |
| 47 | |
| 48 | ## Delete a release |
| 49 | |
| 50 | Open the release and choose **Delete release**. The tag stays: delete it |
| 51 | with git. |
| 52 | |
| 53 | ```sh |
| 54 | git push origin :refs/tags/v1.2.0 |
| 55 | ``` |
| 56 | |
| 57 | ## Workflows and webhooks |
| 58 | |
| 59 | Each change to a release starts the repository's workflows that run |
| 60 | `on: release`, at the commit its tag names, and is sent to webhooks as |
| 61 | `release.created`, `release.published` and the rest. See |
| 62 | [releases in Actions](/guides/actions/#releases) for which change is which |
| 63 | activity type, and [webhooks](/guides/webhooks/) for what each event |
| 64 | carries. A release a workflow job's own token makes starts no workflows. |
| 65 | |
| 66 | ## From the API and MCP |
| 67 | |
| 68 | | Route | MCP | What it does | |
| 69 | | --- | --- | --- | |
| 70 | | [`GET /repos/{owner}/{name}/releases`](/reference/api/releases/list-releases/) | `repository` `list_releases` | Releases, newest first, at most 100. Drafts only for the Write role. | |
| 71 | | [`POST /repos/{owner}/{name}/releases`](/reference/api/releases/create-release/) | `repository` `create_release` | Publish a release: `tag_name`, `target`, `release_name`, `body`, `draft`, `prerelease`. | |
| 72 | | [`GET /repos/{owner}/{name}/releases/latest`](/reference/api/releases/get-latest-release/) | `repository` `latest_release` | The latest release. | |
| 73 | | [`GET /repos/{owner}/{name}/releases/tags/{tag}`](/reference/api/releases/get-release-by-tag/) | `repository` `get_release_by_tag` | The release of one tag. | |
| 74 | | [`GET /repos/{owner}/{name}/releases/{id}`](/reference/api/releases/get-release/) | `repository` `get_release` | One release by its id (`rel_…`). | |
| 75 | | [`PATCH /repos/{owner}/{name}/releases/{id}`](/reference/api/releases/update-release/) | `repository` `update_release` | Change its `release_name`, `body`, `draft` or `prerelease`. `draft: false` publishes it. | |
| 76 | | [`DELETE /repos/{owner}/{name}/releases/{id}`](/reference/api/releases/delete-release/) | `repository` `delete_release` | Delete it; the tag stays. | |
| 77 | |
| 78 | Under a repository's address `name` is the repository's, so a release's |
| 79 | title is sent as `release_name` and comes back as `name`. |
| 80 | |
| 81 | ```sh |
| 82 | curl -X POST https://api.g1t.sh/repos/flagon-io/hello/releases \ |
| 83 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 84 | -d '{"tag_name": "v1.2.0", "release_name": "Greetings by name", "body": "## What changed\n\n- Greets the caller by name"}' |
| 85 | ``` |
| 86 | |
| 87 | Reading releases takes the `repo:read` scope; publishing, changing and |
| 88 | deleting them take `repo:write`. |