enaloo.com
Color theme
Skip to the guide
All guides
RTLY-Kit

Verifying releases

How to check that a release archive is the file the release workflow built, with a checksum and a build provenance attestation, and how this relates to a Composer install.

app RTLY-Kit 0.2.0checked reading 3 minutes

On this page

What a release contains

Pushing a version tag such as v0.2.0 starts the release workflow in the GitHub repository. Before it builds anything, it checks four things. The tag is a valid version. The newest section of CHANGELOG.md has the same version. The tagged commit is part of the main branch. The CI run for that commit is green. If one check fails, nothing is published.

Then it builds the archives with git archive. Files marked export-ignore (tests, the guide sources, tool and CI files, composer.lock) are left out. The GitHub Release for that tag has these files:

  • rtly-kit-X.Y.Z.tar.gz and rtly-kit-X.Y.Z.zip , the same commit in two formats.
  • SHA256SUMS , the SHA-256 checksum of both archives.
  • A signed build provenance attestation for both archives, stored by GitHub. It is not a file on the release page.

Note. Only releases published by this workflow have these files. An older release may have none of them. Replace X.Y.Z with the version you downloaded.

Check the checksum

Download the archive and SHA256SUMS into one folder, then run:

Bash
sha256sum --check SHA256SUMS

Each line must end with OK. If you downloaded only the .tar.gz, the command reports the missing .zip as an error. Use sha256sum --check --ignore-missing SHA256SUMS in that case. On macOS use shasum -a 256 -c SHA256SUMS.

A checksum shows that your download is not damaged and is the file named in SHA256SUMS. Both files come from the same release page, so the checksum alone does not protect you from someone who can change that page. For that, use the attestation.

Check the build provenance

With the GitHub CLI (opens in a new tab) installed:

Bash
gh attestation verify rtly-kit-X.Y.Z.tar.gz --repo ehsanenaloo/RTLY-Kit

The command looks up the attestation that GitHub Actions signed for this exact file and checks it. A success message means a workflow run in the ehsanenaloo/RTLY-Kit repository produced the archive, and the file has not changed since. Run the same command for the .zip if you use it.

Packagist and Composer installs

Packagist learns about a new tag through its own webhook, so composer require tsi/rtly-kit installs the code of the same tag. The release workflow runs only for a tagged commit that is on main.

The archive that Composer downloads is generated by GitHub for the tag. It is not the file attested above. To see which commit you got, look in your composer.lock under tsi/rtly-kit. The source.reference value is the commit hash. Compare it with the tag:

Bash
git ls-remote https://github.com/ehsanenaloo/RTLY-Kit refs/tags/vX.Y.Z

For a tag that points to a commit, the hash printed there is the one in your lock file. An annotated tag also prints a second line ending in ^{}. That line is the commit.

What this does not cover

  • It does not review the code. It shows where an archive came from. See Accuracy and data for what we checked in the reference data.
  • Git tags are not signed. The checks above rely on the repository, its workflow and the GitHub attestation service.
  • There is no separate software bill of materials. The package has no required dependencies (see Installation ).

To report a security problem in a release, see SECURITY.md in the repository.