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

# vers repo tag create

Create a tag inside a repo that points to a specific commit. Tags are movable named pointers, think `latest`, `v1.2.0`, `staging`, `known-good`.

## Synopsis

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

## Description

Creates a new tag inside the given repository pointing at the commit. The tag is unique per-repo; you can't have two tags with the same name in the same repo (but `my-app:latest` and `other-app:latest` coexist fine).

Tag names: 1-128 characters, letters, digits, hyphens, underscores, dots.

<Info>
  The commit must be owned by your org. You cannot tag another org's commit, even if you can see it through a public repo. The way to "import" someone else's commit is `vers repo fork`, which re-commits it under your ownership.
</Info>

## Options

| Option                | Description                                      |
| --------------------- | ------------------------------------------------ |
| `--description`, `-d` | Optional description of what this tag represents |

## Examples

### Tag the result of a commit

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

vers repo tag create my-app latest c7e4a2f1-…
# ✓ Tag created → my-app:latest
```

### Tag with a description

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag create my-app known-good c7e4a2f1-… \
    -d "Last build that passed the integration suite"
```

### Chain from a previous tag lookup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Move a curated snapshot: look up one tag's commit, point another tag at it
COMMIT=$(vers repo tag get my-app staging --format json | jq -r .commit_id)
vers repo tag create my-app production "$COMMIT" -d "Promoted from staging"
```

## Error Cases

### Repository not found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag create ghost latest c7e4…
# Error: repository not found
```

### Commit not found or not yours

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag create my-app latest 00000000-…
# Error: commit not found
# or: forbidden   (if the commit exists but your org doesn't own it)
```

**Solution for "forbidden":** you're trying to tag someone else's commit. Use `vers repo fork` instead.

### Tag already exists

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag create my-app latest c9e4…
# Error: tag already exists in repository
```

**Solution:** use [`vers repo tag update`](/cli-reference/repo-tag-update) to move the existing tag to a new commit, or delete it first with [`vers repo tag delete`](/cli-reference/repo-tag-delete).

### Invalid tag name

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers repo tag create my-app "my tag" c7e4…
# Error: Tag name can only contain alphanumeric characters, hyphens, underscores, and dots
```

## See Also

* [`vers repo tag update`](/cli-reference/repo-tag-update) - move an existing tag
* [`vers repo tag list`](/cli-reference/repo-tag-list)
* [Repositories and Tags](/repositories)