Managing releases in a repository

You can create releases to bundle and deliver iterations of a project to users.

Who can use this feature?

Repository collaborators and people with write access to a repository can create, edit, and delete a release.

Tool navigation

In this article

About release management

You can create new releases with release notes, @mentions of contributors, and links to binary files, as well as edit or delete existing releases. You can also create, modify, and delete releases by using the Releases API. For more information, see REST API endpoints for releases in the REST API documentation.

Creating a release

Tip

If you have enabled immutable releases for your repository, it's recommended to create releases as drafts first, attach all assets, and then publish. This ensures all assets are in place before the release becomes immutable. For more information, see Immutable releases.

  1. On GitHub, navigate to the main page of the repository.

  2. To the right of the list of files, click Releases.

    Screenshot of the main page of a repository. A link, labeled "Releases", is highlighted with an orange outline.

  3. At the top of the page, click Draft a new release.

  4. To choose a tag for the release, select the Choose a tag dropdown menu.

    • To use an existing tag, click the tag.
    • To create a new tag, type a version number for your release, then click Create new tag.

  5. If you created a new tag, select the Target dropdown menu, then click the branch that contains the project you want to release.

  6. Optionally, above the description field, select the Previous tag dropdown menu, then click the tag that identifies the previous release.

    Screenshot of the "New release" form. A dropdown menu, labeled "Previous tag: auto", is highlighted with an orange outline.

  7. In the "Release title" field, type a title for your release.

  8. In the "Describe this release" field, type a description for your release. If you @mention anyone in the description, the published release will include a Contributors section with an avatar list of all the mentioned users. Alternatively, you can automatically generate your release notes by clicking Generate release notes.

  9. Optionally, to include binary files such as compiled programs in your release, drag and drop or manually select files in the binaries box.

  10. Optionally, to notify users that the release is not ready for production and may be unstable, select This is a pre-release.

  11. Optionally, select Set as latest release. If you do not select this option, the latest release label will automatically be assigned based on semantic versioning.

  12. Optionally, if GitHub Discussions is enabled for the repository, create a discussion for the release.

    • Select Create a discussion for this release.