How to Package a Software Release Using REST API

[loujr]

A release is a specific version of your software that can be downloaded and deployed. In this article we will walk through the steps of tagging and packaging a software release using GitHub's REST API.

On the surface, everything starts with a commit. The idea of tagging a commit and turning it into a release is that this particular set of changes is special and set aside from the rest of the events in a repository.

There are three steps to packaging a software release:

1. Tagging a Commit
2. Creating a Release
3. Uploading a Release Asset

Tagging a Commit

A release is based on a git tag, which is a human readable name for a specific git commit that you can reference later. Tags can be divided into two groups to mark releases:

• Lightweight Tags only include information on a commit. Lightweight tags only need one API call to Create a Reference.

• Annotated Tags include information on the tagger, the date the commit was tagged, and also an annotation message. If you are using annotated tags, you have to first Create a Tag Object then Create a Reference.

In this example, we will be creating an annotated tag. To accomplish this, you must first make an API call to /git/tags to create the tag object.

CREATE A TAG OBJECT

To create an annotated tag, you need to create a tag object. Annotated tags contain more information that a lightweight tag. Namely these tags answer the questions: who tagged this commit and why did they tag it. The following is an example API call that was made to the test organization Evil Corp. For tag objects, there are two elements:

1. Contents of the Tag - This includes the information regarding the commit you have just taged
2. Information About the Tagger - This is separate from the authorship of the commit

curl -i -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer 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" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/the-evil-corporation/test-triple5/git/tags -d '{"tag":"v1.2.1","message":"Version 1.2","object":"7782c30c43e49f2a002156c9a0387eef62cee11c","type":"commit","tagger":{"name":"Monalisa Octocat","email":"octocat@github.com","date":"2023-03-14T14:53:35-07:00"}}'

tag - the name of your tag, most often this is a version number (e.g., "v0.0.1")

message - additional information you would like to include with the tag

object - the commit SHA of the commit you are tagging

type - type of object you are tagging, a majority of the time this is a commit. However, you can also tag trees or blobs

tagger - this is information regarding who tagged the commit, their email, and the date they specified for the tag.

The response of this request should show HTTP/2 201 if successful.

Note: In this example we used a GitHub Personal Access Token which shows x-ratelimit-remaining: 4995 this means we have successfully authenticated. If this value shows 60, then you have not successfully authenticated against this endpoint and need to try again.

HTTP/2 201 
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, admin:ssh_signing_key, codespace, delete:packages, delete_repo, gist, notifications, project, repo, user, workflow, write:discussion, write:packages
x-accepted-oauth-scopes: 
location: https://api.github.com/repos/the-evil-corporation/test-triple5/git/tags/925e06a1b16f55e866d70d85620314893146f440
x-github-media-type: github.v3; format=json
x-github-api-version-selected: 2022-11-28
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4995
x-github-request-id: CBC5:4F37:6C89C8:DEF701:642B86B6

The response includes the following:

• the tag object that was created
• the commit object that the tag was created from

To create the reference, you need the tag object SHA. In this output, the object is "sha": "925e06a1b16f55e866d70d85620314893146f440".

{
  "node_id": "TA_kwDOJGLEfdoAKDkyNWUwNmExYjE2ZjU1ZTg2NmQ3MGQ4NTYyMDMxNDg5MzE0NmY0NDA",
  "sha": "925e06a1b16f55e866d70d85620314893146f440",
  "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/git/tags/925e06a1b16f55e866d70d85620314893146f440",
  "tagger": {
    "name": "Monalisa Octocat",
    "email": "octocat@github.com",
    "date": "2023-03-14T21:53:35Z"
  },
  "object": {
    "sha": "7782c30c43e49f2a002156c9a0387eef62cee11c",
    "type": "commit",
    "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/git/commits/7782c30c43e49f2a002156c9a0387eef62cee11c"
  },
  "tag": "v1.2",
  "message": "Version 1.2",
  "verification": {
    "verified": false,
    "reason": "unsigned",
    "signature": null,
    "payload": null
  }
}

CREATE A REFERENCE

A Reference is pointer to a commit SHA in a repository. It's a value that tells git how to locate objects. Once you have created a tag object, you need to create the reference so that git knows about the object you have just created. To do this, you will make the following API call to /git/refs:

curl -i -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer 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" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/the-evil-corporation/test-triple5/git/refs -d '{"ref":"refs/tags/v1.2","sha":"925e06a1b16f55e866d70d85620314893146f440"}'

A ref is the name of the reference you are creating. Because we created an annotated tag, this should match your tag object.

The sha needs to be your tag object you have created. If you are using a lightweight tag, then you will use the commit SHA.

If successfull you will received a HTTP/2 201 response.

HTTP/2 201 
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, admin:ssh_signing_key, codespace, delete:packages, delete_repo, gist, notifications, project, repo, user, workflow, write:discussion, write:packages
x-accepted-oauth-scopes: repo
location: https://api.github.com/repos/the-evil-corporation/test-triple5/git/refs/tags/v1.2
x-github-media-type: github.v3; format=json
x-github-api-version-selected: 2022-11-28
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4993
x-ratelimit-reset: 1680576916
x-github-request-id: CC4E:6FB8:778F11:F50DAB:642B8ACC

The response shows that an annotated git tag was created for the commit you have just made. This tag contains additional information that you inserted into your tag object.

{
  "ref": "refs/tags/v1.2",
  "node_id": "REF_kwDOJGLEfa5yZWZzL3RhZ3MvdjEuMg",
  "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/git/refs/tags/v1.2",
  "object": {
    "sha": "925e06a1b16f55e866d70d85620314893146f440",
    "type": "tag",
    "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/git/tags/925e06a1b16f55e866d70d85620314893146f440"
  }
}

Once you have created the tag, it will also appear in GitHub's UI.

Creating a Release

To turn your tag into a release, you need to make an API call to /releases.

curl -i -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer 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" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/the-evil-corporation/test-triple5/releases -d '{"tag_name":"v1.2","target_commitish":"main","name":"Hello World v1.2","body":"The only print statement you will ever need","draft":false,"prerelease":false,"generate_release_notes":false}'

tag_name - the name of your tag that you created in your reference.

target_commitish - the name of the branch where your tag is located.

name - The name of your release. This will appear in GitHub's UI.

body - Information about your release. This will also appear in GitHub's UI under your release information.

There is an option to generate release notes as well as to do a pre-release. If successful, the header information will return HTTP/2 201.

HTTP/2 201 
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, admin:ssh_signing_key, codespace, delete:packages, delete_repo, gist, notifications, project, repo, user, workflow, write:discussion, write:packages
x-accepted-oauth-scopes: repo
location: https://api.github.com/repos/the-evil-corporation/test-triple5/releases/98122155
x-github-media-type: github.v3; format=json
x-github-api-version-selected: 2022-11-28
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4998
x-ratelimit-reset: 1680657520
x-github-request-id: E2EB:4484:25247A:4C87A7:642CBEF9

The following response contains all the information about the release you have just made. The release id "id": 98122155 is important because we will use it to upload release assets in the next step. It is important to note that you can name your tag differently than your release name. In this example, our release is "name": "Hello World v1.2" but our tag is simply "tag_name": "v1.2". Depending on the versioning requirements regarding tags within your organization, you can make additional adjustments as necessary.

{
  "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/releases/98122155",
  "assets_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/releases/98122155/assets",
  "upload_url": "https://uploads.github.com/repos/the-evil-corporation/test-triple5/releases/98122155/assets{?name,label}",
  "html_url": "https://github.com/the-evil-corporation/test-triple5/releases/tag/v1.2",
  "id": 98122155,
  "author": {
    "login": "loujr",
    "id": 61295275,
    "node_id": "MDQ6VXNlcjYxMjk1Mjc1",
    "avatar_url": "https://avatars.githubusercontent.com/u/61295275?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/loujr",
    "html_url": "https://github.com/loujr",
    "followers_url": "https://api.github.com/users/loujr/followers",
    "following_url": "https://api.github.com/users/loujr/following{/other_user}",
    "gists_url": "https://api.github.com/users/loujr/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/loujr/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/loujr/subscriptions",
    "organizations_url": "https://api.github.com/users/loujr/orgs",
    "repos_url": "https://api.github.com/users/loujr/repos",
    "events_url": "https://api.github.com/users/loujr/events{/privacy}",
    "received_events_url": "https://api.github.com/users/loujr/received_events",
    "type": "User",
    "site_admin": true
  },
  "node_id": "RE_kwDOJGLEfc4F2Tmr",
  "tag_name": "v1.2",
  "target_commitish": "main",
  "name": "Hello World v1.2",
  "draft": false,
  "prerelease": false,
  "created_at": "2023-03-14T21:53:35Z",
  "published_at": "2023-04-05T00:21:13Z",
  "assets": [
  ],
  "tarball_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/tarball/v1.2",
  "zipball_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/zipball/v1.2",
  "body": "The only print statement you will ever need"
}

Finally, our release now appears in GitHub's UI.

Uploading a Release Asset

A release asset is an artifact that provides a rusable set of tools to be used during the creation, development, or delivery of software development. Release assets can include binary files, release notes, software licensing, and anything that should be packaged along with your software for the end user.

Before uploading a release asset, you need the release id. You will have received one in the output of the release you created. However, if you do not remember your release id, you can make an API call to the /releases endpoint.

GET A RELEASE ID

To get your release id in order to upload a release asset, you need to make an API call to the /releases endpoint. For this example, because we are using the latest release we can make an API call to /releases/latest:

curl -i -L -H "Accept: application/vnd.github+json" -H "Authorization: Bearer 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" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/the-evil-corporation/test-triple5/releases/latest

If this request was successful, your header information will return HTTP/2 200

HTTP/2 200 
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, admin:ssh_signing_key, codespace, delete:packages, delete_repo, gist, notifications, project, repo, user, workflow, write:discussion, write:packages
x-accepted-oauth-scopes: repo
x-github-media-type: github.v3; format=json
x-github-api-version-selected: 2022-11-28
x-ratelimit-limit: 5000
x-ratelimit-remaining: 4997
x-ratelimit-reset: 1680657520
x-github-request-id: E4CB:42E6:108034:21F367:642CC5F4

Your release id will appear in the return. In this example, our release id is "id": 98122155 this id will allow you to upload release assets to your release version.

{
  "url": "https://api.github.com/repos/the-evil-corporation/test-triple5/releases/98122155",
  "assets_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/releases/98122155/assets",
  "upload_url": "https://uploads.github.com/repos/the-evil-corporation/test-triple5/releases/98122155/assets{?name,label}",
  "html_url": "https://github.com/the-evil-corporation/test-triple5/releases/tag/v1.2",
  "id": 98122155,
  "author": {
    "login": "loujr",
    "id": 61295275,
    "node_id": "MDQ6VXNlcjYxMjk1Mjc1",
    "avatar_url": "https://avatars.githubusercontent.com/u/61295275?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/loujr",
    "html_url": "https://github.com/loujr",
    "followers_url": "https://api.github.com/users/loujr/followers",
    "following_url": "https://api.github.com/users/loujr/following{/other_user}",
    "gists_url": "https://api.github.com/users/loujr/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/loujr/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/loujr/subscriptions",
    "organizations_url": "https://api.github.com/users/loujr/orgs",
    "repos_url": "https://api.github.com/users/loujr/repos",
    "events_url": "https://api.github.com/users/loujr/events{/privacy}",
    "received_events_url": "https://api.github.com/users/loujr/received_events",
    "type": "User",
    "site_admin": true
  },
  "node_id": "RE_kwDOJGLEfc4F2Tmr",
  "tag_name": "v1.2",
  "target_commitish": "main",
  "name": "Hello World v1.2",
  "draft": false,
  "prerelease": false,
  "created_at": "2023-03-14T21:53:35Z",
  "published_at": "2023-04-05T00:21:13Z",
  "assets": [
  ],
  "tarball_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/tarball/v1.2",
  "zipball_url": "https://api.github.com/repos/the-evil-corporation/test-triple5/zipball/v1.2",
  "body": "The only print statement you will ever need"
}

UPLOAD A RELEASE ASSET

Once you have your release id, you can make an API call to /releases/assets. In this example, we have created evil.zip. This zip file contains the evil license and evil release notes. However, you can zip up anything you think people will need in order to use your software. For this API call, you are not going to use api.github.com like we have been using in the previous sections. Instead, you will upload through uploads.github.com. Additionally, you will need to enclose your URL in quotes for this to be effective.

Once you have packaged your zip file, you can now upload your assets.

curl -i -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer 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" -H "X-GitHub-Api-Version: 2022-11-28" -H "Content-Type: application/octet-stream" "https://uploads.github.com/repos/the-evil-corporation/test-triple5/releases/98122155/assets?name=evil.zip" --data-binary "@evil.zip"

If successful, your header information should return HTTP/2 201.

HTTP/2 201 
x-accepted-oauth-scopes: repo
x-content-type-options: nosniff
x-frame-options: deny
x-github-media-type: github.v3; format=json
x-github-tenant: 
x-oauth-scopes: admin:enterprise, admin:gpg_key, admin:org, admin:org_hook, admin:public_key, admin:repo_hook, admin:ssh_signing_key, codespace, delete:packages, delete_repo, gist, notifications, project, repo, user, workflow, write:discussion, write:packages
x-xss-protection: 1; mode=block
x-github-request-id: E55A:7569:1E6A5:30BF5:642CC7C2

The response shows the details of your newly uploaded asset.

{"url":"https://api.github.com/repos/the-evil-corporation/test-triple5/releases/assets/102344721","id":102344721,"node_id":"RA_kwDOJGLEfc4GGagR","name":"evil.zip","label":"","uploader":{"login":"loujr","id":61295275,"node_id":"MDQ6VXNlcjYxMjk1Mjc1","avatar_url":"https://avatars.githubusercontent.com/u/61295275?v=4","gravatar_id":"","url":"https://api.github.com/users/loujr","html_url":"https://github.com/loujr","followers_url":"https://api.github.com/users/loujr/followers","following_url":"https://api.github.com/users/loujr/following{/other_user}","gists_url":"https://api.github.com/users/loujr/gists{/gist_id}","starred_url":"https://api.github.com/users/loujr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/loujr/subscriptions","organizations_url":"https://api.github.com/users/loujr/orgs","repos_url":"https://api.github.com/users/loujr/repos","events_url":"https://api.github.com/users/loujr/events{/privacy}","received_events_url":"https://api.github.com/users/loujr/received_events","type":"User","site_admin":true},"content_type":"application/octet-stream","state":"uploaded","size":419,"download_count":0,"created_at":"2023-04-05T00:58:42Z","updated_at":"2023-04-05T00:58:42Z","browser_download_url":"https://github.com/the-evil-corporation/test-triple5/releases/download/v1.2/evil.zip"}

Finally, your release as well as your assets appear under your release version within GitHub's UI.

If you have made it to the end, congratulations on your software release. For other API functions within GitHub, please check out the list of REST API Endpoints.

[amitdevteams]

very informatics thanks for sharing

[Bonifase]

Awesome.

[Enochada]

Awesome

[AkdM]

Thanks for the sum up, that was very useful!

[andialfiann]

great