gh release list: List Releases in a Repo
gh release list prints the releases in a repository, newest first, with draft and prerelease markers.
Discovery jobs that need the latest stable tag, or that audit which versions are published, start with gh release list.
What it does
gh release list returns releases sorted by creation date, showing the title, type (latest, draft, prerelease), tag, and publish date. --json yields the same data as fields for scripting the latest tag.
Common usage
gh release list
gh release list --limit 5
gh release list --exclude-drafts --exclude-pre-releases
gh release list --json tagName,isLatest --jq '.[] | select(.isLatest) | .tagName'Flags
| Flag | What it does |
|---|---|
| -L, --limit <n> | Maximum number of releases to list |
| --exclude-drafts | Omit draft releases |
| --exclude-pre-releases | Omit prereleases |
| --json <fields> | Output selected fields as JSON |
| -q, --jq <expression> | Filter JSON output with jq |
| -R, --repo <owner/repo> | Target a specific repository |
In CI
Set GH_TOKEN and permissions: { contents: read }. Draft releases are only visible to tokens with write access, so a read-only token sees fewer entries; combine --json isLatest with --jq to resolve the current stable tag reliably.
Common errors in CI
"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. An empty list where you expected releases usually means they are all drafts and the token is read-only. "could not determine base repository" outside a checkout is fixed with -R owner/repo.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached