# Gitea Actions

Shared composite actions for Gitea CI/CD workflows.

## Actions

### `calver` — CalVer Version Generator

Generates a `YYYY.MM.BUILD` version string from git tags, where BUILD increments per month.

```yaml
- uses: cal/gitea-actions/calver@main
```

**Outputs:**

| Output | Example | Description |
|---|---|---|
| `version` | `2026.3.5` | CalVer version |
| `sha_short` | `abc1234` | Short commit SHA (7 chars) |
| `version_sha` | `2026.3.5-abc1234` | Version with SHA suffix |
| `branch` | `main` | Current branch name |
| `timestamp` | `2026-03-09T12:00:00Z` | UTC timestamp (ISO 8601) |

---

### `docker-tags` — Docker Tag Resolver

Generates Docker image tags based on branch using a channel strategy:

| Branch | Channel | Tags |
|---|---|---|
| `main` | stable | `latest`, `<version>`, `<version>-<sha>` |
| `next-release` | rc | `next-release`, `<version>-rc`, `<version>-rc-<sha>` |
| anything else | dev | `dev`, `dev-<sha>` |

```yaml
- uses: cal/gitea-actions/docker-tags@main
  with:
    image: cal/my-app
    version: ${{ steps.calver.outputs.version }}
    sha_short: ${{ steps.calver.outputs.sha_short }}
```

**Outputs:** `tags` (comma-separated), `channel`, `primary_tag`

---

### `gitea-tag` — Gitea Tag Creator

Creates a git tag via the Gitea API, bypassing branch protection rules.

```yaml
- uses: cal/gitea-actions/gitea-tag@main
  with:
    version: ${{ steps.calver.outputs.version }}
    token: ${{ secrets.GITEA_TOKEN }}
```

**Inputs:**

| Input | Required | Default | Description |
|---|---|---|---|
| `version` | yes | | Tag name |
| `token` | yes | | Gitea API token |
| `server_url` | no | `github.server_url` | Gitea server URL |
| `repository` | no | `github.repository` | Owner/repo path |
| `sha` | no | `github.sha` | Commit SHA to tag |

---

### `python-lint` — Python Linter

Runs `ruff check` via `uvx` — no pip or Python installation required. Bootstraps `uv` automatically if not present on the runner.

```yaml
- uses: cal/gitea-actions/python-lint@main
  with:
    src: app/
```

**Inputs:**

| Input | Default | Description |
|---|---|---|
| `src` | `.` | Source directory or file to check |
| `ruff-version` | latest | Pin a specific ruff version (e.g., `0.9.1`) |
| `extra-args` | | Additional args for `ruff check` (e.g., `--select E,F`) |

---

### `discord-notify` — Discord Webhook Notification

Sends a success or failure embed to a Discord channel.

```yaml
- uses: cal/gitea-actions/discord-notify@main
  with:
    webhook_url: ${{ secrets.DISCORD_WEBHOOK }}
    title: My App
    status: success
    version: ${{ steps.calver.outputs.version }}
    image_tag: ${{ steps.calver.outputs.version_sha }}
    commit_sha: ${{ steps.calver.outputs.sha_short }}
    timestamp: ${{ steps.calver.outputs.timestamp }}
```

**Inputs:**

| Input | Required | Default | Description |
|---|---|---|---|
| `webhook_url` | yes | | Discord webhook URL |
| `title` | yes | | Embed title (e.g., app name) |
| `status` | no | `success` | `success` or `failure` |
| `version` | no | | CalVer version string |
| `image_tag` | no | | Docker image tag |
| `commit_sha` | no | | Short commit SHA |
| `author` | no | `github.actor` | Commit author |
| `run_url` | no | auto-generated | Link to the Actions run |
| `branch` | no | `github.ref_name` | Branch name |
| `timestamp` | no | auto-generated | ISO 8601 timestamp |

## Typical Workflow

Most Python/Docker projects use these actions together:

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: cal/gitea-actions/calver@main
        id: calver

      - uses: cal/gitea-actions/python-lint@main
        with:
          src: app/

      - uses: cal/gitea-actions/docker-tags@main
        id: tags
        with:
          image: cal/my-app
          version: ${{ steps.calver.outputs.version }}
          sha_short: ${{ steps.calver.outputs.sha_short }}

      # ... docker build & push using steps.tags.outputs.tags ...

      - uses: cal/gitea-actions/gitea-tag@main
        with:
          version: ${{ steps.calver.outputs.version }}
          token: ${{ secrets.GITEA_TOKEN }}

      - uses: cal/gitea-actions/discord-notify@main
        if: always()
        with:
          webhook_url: ${{ secrets.DISCORD_WEBHOOK }}
          title: My App
          status: ${{ job.status }}
          version: ${{ steps.calver.outputs.version }}
          image_tag: ${{ steps.calver.outputs.version_sha }}
          commit_sha: ${{ steps.calver.outputs.sha_short }}
          timestamp: ${{ steps.calver.outputs.timestamp }}
```