Working with tags

List a repository's tags and understand annotated vs. lightweight tags.

tags.list / tags.listAll page through a repository’s tags as normalized Tag objects. Some providers supply a tag date and annotation details — check capabilities.tagDates before relying on them.

Listing tags

tags.list returns one Page<Tag>; tags.listAll follows cursors and yields every tag. Both require a repo:

const { data: tags } = await client.tags.list({ repo: 'capawesome-team/repo-sdk' });

for await (const tag of client.tags.listAll({ repo: 'capawesome-team/repo-sdk' })) {
  console.log(tag.name, tag.sha);
}

The normalized Tag

PropType

name?string

The tag name (without the refs/tags/ prefix).

Typestring

sha?string

The commit SHA the tag points at (annotated tags are peeled to the commit).

Typestring

message?string

The tag message, for annotated tags.

Typestring

date?Date

The tag date — only when the provider supplies one (see below).

TypeDate

isAnnotated?boolean

Whether the tag is annotated rather than lightweight.

Typeboolean

raw?unknown

The untouched provider payload.

Typeunknown

Tag dates are provider-dependent

if (client.capabilities.tagDates) {
  for (const tag of tags) {
    console.log(tag.name, tag.date); // a Date on GitLab/Bitbucket
  }
}

isAnnotated distinguishes annotated tags (which carry their own object and message) from lightweight tags. When available it’s derived from whether the provider returns an annotation for the tag.

Getting a single tag

tags.get fetches one tag by its exact name and throws a RepoError with code: 'not_found' on a miss. Annotated tags are always peeled — sha is the tagged commit, not the tag object:

const tag = await client.tags.get({ repo: 'capawesome-team/repo-sdk', name: 'v1.0.0' });
console.log(tag.sha, tag.isAnnotated);

Unlike the listing, tags.get on GitHub can supply message and date for annotated tags (they come from the tag object itself); capabilities.tagDates continues to describe the listing.

Next: Downloading code

Stream a repository archive or get an authenticated clone URL.

Working with branches

List a repository’s branches as normalized Branch objects.