diff --git a/README.md b/README.md new file mode 100644 index 0000000..f05f79e --- /dev/null +++ b/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`, ``, `-` | +| `next-release` | rc | `next-release`, `-rc`, `-rc-` | +| anything else | dev | `dev`, `dev-` | + +```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 }} +``` diff --git a/calver/action.yml b/calver/action.yml index 9014ec2..203d659 100644 --- a/calver/action.yml +++ b/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 diff --git a/discord-notify/action.yml b/discord-notify/action.yml index d36878c..ee5b9e8 100644 --- a/discord-notify/action.yml +++ b/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 diff --git a/docker-tags/action.yml b/docker-tags/action.yml index d7ffd72..333731a 100644 --- a/docker-tags/action.yml +++ b/docker-tags/action.yml @@ -5,6 +5,19 @@ # main -> latest, , - # next-release -> next-release, -rc, -rc- # anything else -> dev, dev- +# +# 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 diff --git a/gitea-tag/action.yml b/gitea-tag/action.yml index a2c9afb..6fedec9 100644 --- a/gitea-tag/action.yml +++ b/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 diff --git a/python-lint/action.yml b/python-lint/action.yml index 6e775d7..339541f 100644 --- a/python-lint/action.yml +++ b/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