> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Repo tag update

# vers repo tag update

Atomically move a tag to a new commit, or change its description. No VMs are touched by this operation; it's a metadata-only pointer update.

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update <repo-name> <tag-name> --commit <new-commit-id>
vers repo tag update <repo-name> <tag-name> --description "new text"
vers repo tag update <repo-name> <tag-name> --commit <id> --description "text"
```

## Description

Updates a tag in place. You must supply at least one of `--commit` or `--description`.

The most common use is advancing a rolling tag like `latest` to point at a new build:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers commit              # → new commit c9e4…
vers repo tag update my-app latest --commit c9e4…
# ✓ Tag 'latest' in 'my-app' updated
```

The previous commit is not deleted; it's simply no longer named by this tag. If you had other tags pointing at it, they're unaffected.

<Info>
  The new commit must be owned by your org, same rule as `vers repo tag create`.
</Info>

## Options

| Option                | Description                    |
| --------------------- | ------------------------------ |
| `--commit`            | Move the tag to this commit ID |
| `--description`, `-d` | New description for the tag    |

## Examples

### Rolling `latest` forward after a new build

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers commit
# ✓ Commit c9e4… created

vers repo tag update my-app latest --commit c9e4…
```

### Rolling back

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Your team's latest is broken; pin it to the previous known-good commit.
OLD=$(vers repo tag get my-app known-good --format json | jq -r .commit_id)
vers repo tag update my-app latest --commit "$OLD"
```

### Editing the description

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update my-app known-good -d "2026-04-17 release candidate"
```

### Both at once

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update my-app staging --commit c9e4… -d "Rebuilt after migration 0042"
```

## Error Cases

### Repository or tag not found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update ghost latest --commit c9e4…
# Error: Repository, tag, or commit not found
```

### Commit not found or forbidden

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update my-app latest --commit 00000000-…
# Error: commit not found
# or: forbidden   (commit exists in another org)
```

### Nothing to update

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag update my-app latest
# Error: at least one of --commit or --description must be provided
```

## Notes

The CLI currently cannot clear a description (send `null`). The underlying API supports it via `PATCH` with an explicit `null` field, but the current `vers repo tag update` flags only let you overwrite with a new string or skip the field entirely.

## See Also

* [`vers repo tag get`](/cli-reference/repo-tag-get)
* [`vers repo tag create`](/cli-reference/repo-tag-create)
* [CI: maintaining a `latest` image](/examples/ci-latest-image)