# gh release list: List Releases in a Repo

> gh release list shows releases with their tags, types, and dates. Reference for --limit, --exclude-drafts, --json, and the auth errors seen in CI.

Source: https://latchkey.dev/learn/command-reference/gh-release-list  
Updated: 2026-06-30

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

```Terminal
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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### gh release list: List Releases in a Repo?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt