gitea-actions/README.md

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.

- 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>

- 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.

- 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.

- 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.

- 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:

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 }}