release naming convention #10416

There isn't a gh command that prints the convention, but GitHub's source archives are named <repo>-<tag> (for example binbows-1.2.3.zip) and the archive contains a single top-level directory with the same <repo>-<tag> name.

Practical approach in a script:

dir=$(mktemp -d)
gh release download --repo OWNER/REPO --archive=zip --dir "$dir"
archive=$(find "$dir" -maxdepth 1 -type f -name '*.zip' | head -1)
unzip -q "$archive" -d "$dir"
srcdir=$(find "$dir" -maxdepth 1 -mindepth 1 -type d | head -1)
cd "$srcdir"

Using find to discover the extracted directory is more robust than hard-coding the name, since tag formatting can vary (e.g. v1.2.3).

If this answers it, please mark this comment as the answer — thanks!

There is a convention, and it is stable enough to rely on — but you do not need to guess it, because gh can tell you.

The convention for source archives (the auto-generated ones):

• Zip: <repo>-<tag-without-v-prefix>/
• Tar.gz: <repo>-<tag-without-v-prefix>/

Specifically: GitHub strips a leading v from the tag and appends the repository name. So v1.2.3 on repo cli/cli unpacks into cli-1.2.3/, while release-2026-10 unpacks into cli-release-2026-10/.

Two caveats that break the assumption:

1. Not every tag starts with v — which is exactly why the folder name looks inconsistent to you.
2. Uploaded assets are not archives at all. If the release ships its own foo.zip instead of the auto-generated source archive, there is no enclosing directory.

The reliable approach — ask instead of guessing:

tag=$(gh release view "$TAG" --repo "$REPO" --json tagName --jq .tagName)

then, instead of predicting the folder, extract into your own directory:

gh release download "$TAG" --repo "$REPO" --archive=tar.gz
mkdir -p src && tar -xzf ./*.tar.gz -C src --strip-components=1
cd src

--strip-components=1 removes whatever the top-level directory happens to be called — the folder name stops mattering entirely. For zip, use unzip then move, or:

gh release download "$TAG" --repo "$REPO" --archive=zip
mkdir -p src && unzip -q ./*.zip -d src
cd src/*/ && mv * .. 2>/dev/null; cd ..

If you specifically want the folder name as data: gh release view --json assets lists uploaded assets, but the source-archive folder name is never exposed as a field — it is derived. So the deterministic rule above (repo + - + tag minus leading v) is your best bet, with --strip-components=1 as the version that cannot break.