# Tag Management API

Base URL: `${FORGEJO_URL}/api/v1`

## List Tags

```
GET /repos/{owner}/{repo}/tags
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags?page=1&limit=20"
```

**Response:** Array of `Tag` objects:
| Field | Type | Description |
|-------|------|-------------|
| name | string | Tag name |
| id | string | Tag SHA |
| message | string | Tag message (annotated tags) |
| commit | object | Commit the tag points to |
| zipball_url | string | URL for zip archive |
| tarball_url | string | URL for tar archive |

**Example Response:**
```json
[
  {
    "name": "v1.2.0",
    "id": "abc123...",
    "message": "Release v1.2.0",
    "commit": {
      "sha": "def456...",
      "url": "https://{FORGEJO_HOST}/api/v1/repos/{owner}/{repo}/git/commits/def456..."
    },
    "zipball_url": "https://{FORGEJO_HOST}/{owner}/{repo}/archive/{tag}.zip",
    "tarball_url": "https://{FORGEJO_HOST}/{owner}/{repo}/archive/{tag}.tar.gz"
  }
]
```

---

## Create Tag

```
POST /repos/{owner}/{repo}/tags
```

**Request Body (CreateTagOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| tag_name | string | yes | Tag name |
| target | string | no | Branch name or commit SHA (default: default branch HEAD) |
| message | string | no | Tag message (creates annotated tag if provided) |

### Create lightweight tag

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags"
```

### Create annotated tag

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0",
    "message": "Release v1.0.0\n\nFirst stable release with all core features.",
    "target": "{branch_or_sha}"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags"
```

### Create tag from specific commit

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0-rc1",
    "target": "abc123def456",
    "message": "Release candidate 1"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags"
```

---

## Get Tag

```
GET /repos/{owner}/{repo}/tags/{tag}
```

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags/{tag}"
```

Returns a single `Tag` object.

---

## Delete Tag

```
DELETE /repos/{owner}/{repo}/tags/{tag}
```

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/tags/{tag}"
```

Returns `204 No Content` on success.

> **Note:** Protected tags cannot be deleted. Remove tag protection first if needed.

---

## Example: Tag a release

```bash
OWNER="{owner}"
REPO="{repo}"
VERSION="{version}"

# Create the annotated tag
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{
    \"tag_name\": \"${VERSION}\",
    \"target\": \"main\",
    \"message\": \"Release ${VERSION}\"
  }" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/tags"

# Verify the tag
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/tags/${VERSION}" | jq '{name, message, commit: .commit.sha}'
```
