# Ticket 0004: `tag-commit.sh`

**Vaihe:** 4/12
**Status:** pending
**Feature branch:** `feature/0004-tag-commit-sh`
**TDD required:** Yes
**Feature file required:** Yes

**Required context:**
- `docs/test-plan/tdd-guide.md`
- `tests/features/0004-tag-commit.feature`
- Skills: `tdd`, `implementation`, `clean-code`, `bash-script`

---

## TDD — Red-Green-Refactor

### Red
Kirjoita `tests/tag-commit.bats` mock-Gitea API:a vasten:
- `tag-commit.sh "1.2.3.42"` → POST `/api/v1/repos/{repo}/tags` palauttaa 201
- Tagi-muoto sisältää `$GITHUB_RUN_NUMBER`
- API palauttaa 409 (tag jo olemassa) → exit 1
- Tyhjä versio → exit 1

```bash
bats tests/tag-commit.bats
# FAIL
```

### Green
`scripts/tag-commit.sh` — curl POST + virheenkäsittely.

```bash
bats tests/tag-commit.bats
# PASS
```

### Refactor
Varmista tagin oikeellisuus, virheilmoitukset.

## DoD
- [ ] Cucumber: `@ticket-0004 and @mock` → kaikki skenaariot GREEN
- [ ] `tests/tag-commit.bats` — kaikki testit läpi
- [ ] POST `/api/v1/repos/{repo}/tags` onnistuu
- [ ] Virhetilanteet käsitellään (409, tyhjä versio)

---

## Toiminto

Tagittaa commitin versiolla Gitea REST API:n kautta. Kutsutaan `ci-master.yml`:n docker-pushin onnistuttua. Tämän jälkeen `isContainerBuilt()` palauttaa `true` samalle commitille.

## Rajapinta

```bash
tag-commit.sh <version>
```

## Gitea API -kutsu

```
POST /api/v1/repos/{owner}/{repo}/tags
Authorization: token {GITEA_TOKEN}

{
  "tag_name": "{version}",
  "message": "Build #{GITHUB_RUN_NUMBER}",
  "target": "{GITHUB_SHA}"
}
```

## Kutsuesimerkki

```bash
tag-commit.sh "1.2.3.$GITHUB_RUN_NUMBER"
```

## Ympäristömuuttujat

- `GITEA_API_URL` — Org variable
- `GITEA_TOKEN` — Org secret
- `GITHUB_REPOSITORY` — Automaattinen
- `GITHUB_SHA` — Automaattinen
- `GITHUB_RUN_NUMBER` — Automaattinen

## Verifiointi

```bash
bash scripts/tag-commit.sh "1.2.3.42"
```

→ `git tag` näyttää tagin commitilla (tai mock-API palauttaa 201)

## Viitteet

- `docs/shared-scripts.md` — Rajapinnan määrittely
- `docs/config-model.md` — `isContainerBuild()`-mekanismi
- `docs/design-rationale.md` — Periaate 1: Statusviestit committiin