A download link can change after you test it
A docs page that points to /releases/latest/download/tool.zip can silently change the installer your team gets between Tuesday’s test and Thursday’s deployment. If a build record says only “downloaded tool.zip,” you may not be able to reproduce the failure after the project publishes another release.
For an older release, include its tag in the URL. That gives you a stable, readable reference to the release you intended, rather than asking GitHub to choose a release when someone clicks. “Stable” here means the link names a version; it does not guarantee the tag or its asset can never be changed.
This is the practical distinction: use a version-pinned link when readers need the same release you tested, documented, or deployed. Use the latest route when the point of the link is to send people to GitHub’s designated current release. The choice affects documentation, install scripts, and whether a bug report can be reproduced later.
Build a direct link to an older release asset
GitHub’s direct-download URL for a release asset follows this pattern:
https://github.com/OWNER/REPOSITORY/releases/download/TAG/ASSET-NAMEFor example, say a project has an asset named atlas-cli-linux-amd64.tar.gz attached to the release tagged v1.4.2. The direct download URL is:
https://github.com/example-org/atlas-cli/releases/download/v1.4.2/atlas-cli-linux-amd64.tar.gzexample-org/atlas-cli is an illustrative repository name. Replace the owner, repository, tag, and asset filename with the exact values from your project. A typo in the tag or filename will not make GitHub infer what you meant.
To find the right values in GitHub:
- Open the repository’s main page and select Releases.
- Find the older release you need and confirm its tag.
- Check the asset list for the exact filename, then assemble the URL using that tag and filename.
GitHub’s guidance also lets you copy the release URL by right-clicking the release title. That URL takes readers to the release page; add the asset path only when you want to link straight to a file.
Pin the tag, not just the release page
There are two useful destinations for an older release. A release-page link, such as https://github.com/example-org/atlas-cli/releases/tag/v1.4.2, shows release notes and all attached assets. The direct asset link goes straight to one file, which is convenient in an install guide or a download button.
For a scripted download, make redirects and HTTP errors visible instead of saving an error page as though it were an archive:
curl -fL \
-o atlas-cli-linux-amd64.tar.gz \
https://github.com/example-org/atlas-cli/releases/download/v1.4.2/atlas-cli-linux-amd64.tar.gzHere, -L follows redirects and -f makes curl fail on an HTTP error response. The URL includes v1.4.2, so a later release does not change which version this command requests.
If you want users to inspect the release before choosing an asset, link to the tag’s release page instead. If you want a download to happen with one click, use the direct asset URL. Avoid linking to a general releases page and calling it a pinned download: the page itself does not identify one particular asset version.
What GitHub’s latest route promises
For an asset on GitHub’s latest release, use this pattern:
https://github.com/OWNER/REPOSITORY/releases/latest/download/ASSET-NAMEFor the example asset, that becomes:
https://github.com/example-org/atlas-cli/releases/latest/download/atlas-cli-linux-amd64.tar.gzThis route asks GitHub for the asset with that filename on its designated latest release. It does not specify a tag. GitHub’s latest-release route excludes prereleases and drafts, so it is not a way to fetch the newest beta or an unpublished draft.
Do not read “latest” as “the highest semantic version” in every release setup. It is GitHub’s latest-release designation, not a version constraint such as “highest stable version matching v1.*.” If your project has unusual tag names, backfilled releases, or a release process where publication order matters, verify which release GitHub designates as latest before relying on the route.
Choose the URL by what must stay reproducible
Make the decision based on what a reader or process needs the link to do. The same project can reasonably use both URL types in different places; the important thing is to make the policy visible.
| Use case | Better fit | Reason |
|---|---|---|
| Setup guide tested against one release | Tag-specific asset URL | The guide requests the version its instructions were written for. |
| Build or deployment script | Tag-specific URL, plus a checksum check | The build can record and verify which artifact it consumed. |
| Project homepage offering the current stable download | /releases/latest/download/... | Visitors do not need to know the current tag in advance. |
| Pre-release testing instructions | Explicit prerelease tag or release page | The latest route excludes prereleases. |
A concrete split might be a project’s homepage linking to the latest stable installer while its migration guide links to v1.4.2, the version whose behavior the guide describes. That is not inconsistency: one link is a moving convenience, and the other is part of a reproducible instruction.
Decision rule: if changing the file without editing the page or script would be a problem, name the tag. If getting the currently designated stable release is the intended behavior, use the latest route.
A pinned URL is not a checksum
A release is a GitHub-level object associated with a Git tag. The tag identifies a point in the repository’s history; the release adds distribution details such as notes and downloadable assets. That distinction matters because a tag-specific URL names a release, but it does not by itself prove the bytes downloaded today are identical to the bytes downloaded last month.
Git tags are expected to identify a version consistently, but a repository owner can move a tag. Release assets can also be removed or replaced. A pinned path therefore improves traceability, but it is not a cryptographic guarantee that the contents are immutable.
For build pipelines or security-sensitive distribution, record more than the URL. Store the version and verify a published checksum when the project provides one. If you publish the software, document a policy for correcting or replacing assets; changing an already-used tag or file can break reproducibility even when the URL remains unchanged.
This is the tradeoff that a “latest versus pinned” choice alone misses: a versioned link controls which release you request, while a checksum helps verify what you received. They solve related but different problems.
Make automation’s version policy explicit
A shell command that downloads from /latest/ is making a release-selection decision every time it runs. That can be appropriate for an interactive installer, where the goal is to fetch the current stable version. It is a poor default for a build that must be repeatable across machines or reruns.
For automation, put the selected version in a variable or configuration value and use it to construct a tag-specific URL. That makes the version easy to review in logs and change deliberately:
VERSION=v1.4.2
ASSET=atlas-cli-linux-amd64.tar.gz
URL="https://github.com/example-org/atlas-cli/releases/download/${VERSION}/${ASSET}"
curl -fL -o "$ASSET" "$URL"The variable does not add integrity checking, but it makes the version policy obvious. A teammate reviewing a change can see that the build moves from v1.4.2 to another tag instead of discovering that an unpinned download began returning a new file.
Keep human-facing update behavior separate from build behavior. An installer can intentionally resolve the latest route, while a release-validation workflow uses a pinned version and records its checksum. One project may need both, but they should not be hidden behind the same ambiguous “download latest” instruction.
Check the link before publishing it
Before adding a URL to a README, install guide, or release note, test the exact destination rather than only opening the repository’s releases list. A release page can exist while the filename in your direct-download URL is wrong, or while the file is not attached to the release you expected.
- For a pinned link, confirm the tag and asset filename on that release’s page.
- For a latest link, confirm that the intended stable release is GitHub’s designated latest release.
- For a prerelease, do not expect the latest route to select it; use its tag or release page.
- For a script, check that a failed request produces a failure, and verify a checksum if one is available.
- For documentation, say whether the link follows the latest release or stays on a named version.
These checks catch a common communication bug: readers see a button labelled “Download v1.4.2,” but its target uses /latest/. The label promises a fixed version while the URL expresses a moving policy. Make the text and destination agree.
Update one link this week
Choose one download link in a project you maintain and decide whether it is supposed to move. If it documents a specific setup or supports a repeatable build, change it to the tag-specific asset URL and record the tag in the surrounding instructions. If it is a convenience link to the current stable release, keep the latest route and label it accordingly.
Then test the resulting URL and, for automation, inspect what happens when the request fails. That small review can prevent a release update from silently changing a tutorial or build input—and gives the next person a clear answer to the question, “Which version did this link mean?”