Working with releases in SourceCraft

A release is a fixed software product version that comprises a specific set of changes, a tag, a description, and additional resources, such as binaries or archives intended for users or other developers.

Releases offer convenient access to particular repository states for analysis and comparison, off-the-shelf builds for users, and give structure to the project development and versioning history.

Releases in SourceCraft are linked to a repository tag, an indicator of a significant milestone in the project's history. Only one release can be associated with one tag.

For more information, see Releases in SourceCraft.

Creating a release

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.
In the top-right corner, click New release.
Under General information:
1. Select the tag to create your new release from.
  
  Note
  
  You can only select a tag that was not used to create releases.
  
  You can use a pre-created tag or create a new one.
  
  To create a new tag:
  1. In the tag selection field, click .
  2. In the Tag field, enter a name for the tag.
  3. In the Target field, select the branch your new tag will be based on.
  4. Click Save.
2. Enter a name for your release.
Optionally, under Release notes:
- Select the previous release.
- Enter a description of the new release, e.g., specify what has been changed, fixed, or improved, and provide details about the update.
Optionally, under Release assets, click Add asset and select the resource type:
- File: Click Browse and upload a file from your local PC.
  
  Limitations
  
  SourceCraft has limits on the size of files you upload to a release.
- Link: Add a link to an external resource and enter its displayed name.
To add another resource, click Add asset.

To delete a resource, click next to it.
Click Publish release.

Tip

You can also save your release as a draft to modify it later instead of publishing it right away. To do this, click Save draft.

The description and contents of a draft release are available to users with the Repository admin or Repository maintainer roles.

Viewing a release

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.

The page will show a list of releases with their authors, publication dates and times, tags, commits, descriptions, and attached resources.

The list will also highlight the latest release.
Select the release you want to view.

Downloading release assets

Each published release contains the following in the Release assets section:

Automatically generated release source code archives in .zip and .tar.gz formats.
Files attached to the release when it is created or edited.
External resource links.

You can download them using the SourceCraft UI or the REST API.

SourceCraft UI

REST API

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.
In the release card, select an asset in the Release assets section:
- Source code (zip): Download the release source code archive in .zip format.
- Source code (tar.gz): Download the release source code archive in .tar.gz format.
- <file_name>: Download the file attached to the release.
- <Link>: Open an external resource.

You can use the Get Release (By Tag) SourceCraft REST API method to get release asset links. The response will return a list of release assets in the assets field. Each asset contains a download link in one of these fields:

archive_link.link: Link to the release source code archive.
link: Link to attached file or external resource.

To get links to release assets:

Get a personal access token (PAT) for API authentication.

Run this query:

export PAT=<personal_access_token>
curl \
    --request GET \
    --header "Authorization: Bearer $PAT" \
    --url "https://api.sourcecraft.tech/repos/<organization_slug>/<repository_slug>/releases/tag/<release_tag>" | jq

Where:

<organization_slug>: Slug of the organization owning the repository.
<repository_slug>: Slug of the repository the release is published in.
<release_tag>: Tag used to create the release.

Download the release source code archive via the wget utility using the link from the archive_link.link field:
```
wget "<link_from_archive_link.link_field>" --output-document=<file_name>.tar.gz
```
Use the link field value to download a file attached to the release or open an external link.

For more information about authenticating and working with the SourceCraft REST API, see Working with the SourceCraft REST API.

Editing a release

Warning

You can edit only a draft release.

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.
Next to the draft release you want to update, click and select Edit.
Update the release settings and click Update release.

Canceling and deleting a release

Note

You cannot directly delete a published release; you need to cancel it first.

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.
Next to the release you want to cancel, click and select Discard release.

The description and contents of a canceled release remain available to users with the Repository admin or Repository maintainer roles.
To delete a release from the repository, click next to the release, select Delete, and confirm the deletion.

Comparing releases

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code, navigate to Releases.
Next to the relevant release, click Compare and select the release to compare it with.

Useful links

Was the article helpful?

Labels

Creating a tag