Add README and usage headers to all composite actions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,167 @@
+# 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 }}
+```

calver/action.yml

@@ -1,6 +1,17 @@
 # CalVer Version Generator
 # Generates YYYY.MM.BUILD version from git tags
 # BUILD = count of tags matching current month + 1
+#
+# Usage:
+#   - uses: cal/gitea-actions/calver@main
+#     id: calver
+#
+# Outputs:
+#   version     - CalVer version (e.g., 2026.3.5)
+#   sha_short   - Short commit SHA (7 chars)
+#   version_sha - Version with SHA (e.g., 2026.3.5-abc1234)
+#   branch      - Current branch name
+#   timestamp   - UTC timestamp (ISO 8601)
 
 name: CalVer Version
 description: Generate a CalVer (YYYY.MM.BUILD) version from git tags

discord-notify/action.yml

@@ -1,5 +1,13 @@
 # Discord Webhook Notification
 # Sends a success or failure embed to a Discord channel
+#
+# Usage:
+#   - uses: cal/gitea-actions/discord-notify@main
+#     if: always()
+#     with:
+#       webhook_url: ${{ secrets.DISCORD_WEBHOOK }}
+#       title: My App
+#       status: ${{ job.status }}
 
 name: Discord Notification
 description: Send a build notification embed to Discord

docker-tags/action.yml

@@ -5,6 +5,19 @@
 #   main          -> latest, <calver>, <calver>-<sha>
 #   next-release  -> next-release, <calver>-rc, <calver>-rc-<sha>
 #   anything else -> dev, dev-<sha>
+#
+# Usage:
+#   - 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 }}
+#
+# Outputs:
+#   tags        - Comma-separated list of full image tags
+#   channel     - Release channel (stable, rc, dev)
+#   primary_tag - Human-readable tag (latest, next-release, or dev)
 
 name: Docker Tags
 description: Resolve Docker image tags based on branch and CalVer version

gitea-tag/action.yml

@@ -1,5 +1,11 @@
 # Gitea Tag Creator
 # Creates a git tag via the Gitea API (avoids branch protection issues)
+#
+# Usage:
+#   - uses: cal/gitea-actions/gitea-tag@main
+#     with:
+#       version: ${{ steps.calver.outputs.version }}
+#       token: ${{ secrets.GITEA_TOKEN }}
 
 name: Create Gitea Tag
 description: Create a git tag via the Gitea API

python-lint/action.yml

@@ -1,6 +1,11 @@
 # Python Lint
 # Runs ruff check via uvx (no pip install needed)
 # Bootstraps uv if not already available on the runner
+#
+# Usage:
+#   - uses: cal/gitea-actions/python-lint@main
+#     with:
+#       src: app/
 
 name: Python Lint
 description: Run ruff check on Python source code using uvx