ci-cd/README.md

## Actions

This repo provides reusable Gitea Actions as composite actions that can be referenced with `uses:`.

### Bump Version

Creates or updates the version in `package.json`, commits it, creates a matching Git tag, and pushes both.

Inputs:

- `node_version`: Node.js version to use. Default: `24`
- `release_line`: optional release line for dev builds. Format: `<major>.<minor>` or `<major>.<minor>.<patch>`. Overrides branch, PR target, inferred ancestor release branch, and `package.json`.
- `gitea_token`: optional token used for checkout and push

Branch and tag rules:

- `main`: creates release tags from the latest commit message (`release/x.y.z`, `release/x.y`, `hotfix/x.y.z`) or falls back to a patch bump.
- `release/<major>.<minor>` or `release/<major>.<minor>.<patch>`: creates the next beta tag for that release base, e.g. `v2.4.0-beta.3` or `v2.4.1-beta.3`.
- all other branches: create a dev tag for the resolved release base using a UTC timestamp, e.g. `v2.4.0-dev.20260314153045`.

Dev release line resolution order:

- `inputs.release_line`
- current branch if it matches `release/<major>.<minor>` or `release/<major>.<minor>.<patch>`
- PR target branch if it matches `release/<major>.<minor>` or `release/<major>.<minor>.<patch>`
- newest ancestor branch from `origin/release/*` (for feature branches created from release branches outside PR context)
- `major.minor` from `package.json`

If no release line can be resolved for a dev build, the action fails intentionally.

Examples:

Commit message examples on `main`:

- `release/2.4.0` -> `v2.4.0`
- `release/2.4` -> `v2.4.0`
- `hotfix/2.4.1` -> `v2.4.1`

Branch examples:

- `release/2.4` -> next `v2.4.0-beta.N`
- `release/v2.4.1` -> next `v2.4.1-beta.N`
- feature branch in a PR to `release/2.4` -> `v2.4.0-dev.<UTC_TIMESTAMP>`
- feature branch created from `release/v2.4.1` (without PR base) -> `v2.4.1-dev.<UTC_TIMESTAMP>` when the release branch tip is an ancestor
- feature branch outside a PR with `package.json` version `2.4.0` -> `v2.4.0-dev.<UTC_TIMESTAMP>`
- feature branch outside a PR with `release_line: 2.4` -> `v2.4.0-dev.<UTC_TIMESTAMP>`

Example:

```yaml
jobs:
  bump-version:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: tanztee/ci-cd/.github/actions/bump-version@main
        with:
          gitea_token: ${{ secrets.GITEA_TOKEN }}
```

Feature branch outside a PR:

```yaml
jobs:
  bump-version:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: tanztee/ci-cd/.github/actions/bump-version@main
        with:
          gitea_token: ${{ secrets.GITEA_TOKEN }}
          release_line: 2.4
```

### Build and Push Docker Image

Example:

```yaml
jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: tanztee/ci-cd/.github/actions/build-and-push@main
        with:
          registry: ${{ secrets.REGISTRY }}
          registry_username: ${{ secrets.REGISTRY_USERNAME }}
          registry_password: ${{ secrets.REGISTRY_PASSWORD }}
```

### Deploy Image to Kubernetes

Example:

```yaml
on:
  workflow_dispatch:
    inputs:
      tag:
        description: Image tag to deploy (e.g. v1.2.3)
        required: true
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: tanztee/ci-cd/.github/actions/deploy-k8s@main
        with:
          tag: ${{ inputs.tag }}
          namespace: oumta-dev
          kubeconfig: ${{ secrets.KUBECONFIG }}
          registry: ${{ secrets.REGISTRY }}
```

## Woodpecker plugins

Plugins are Docker images built from `woodpecker/<name>/` by `.woodpecker/plugins.yaml`. A tag `<name>-vX.Y.Z` publishes `git.uesome.de/actions/ci-cd/<name>:vX.Y.Z`; pipelines pin that version. The push uses `oumta-ci` with the Woodpecker secret `oumta_ci_token`, so `oumta-ci` needs package write access in the org `actions`.

The secret `oumta_ci_token` holds the one token `oumta-ci` writes with. Limit it in Woodpecker to the images `woodpeckerci/plugin-docker-buildx:6`, `git.uesome.de/actions/ci-cd/bump` and `git.uesome.de/actions/ci-cd/deploy` and to the events `push`, `tag` and `manual` (zugaenge.md in oumta-deploy).

### deploy

Writes a pushed dev or beta image with its digest to `tanztee/oumta-deploy` (D16 there). `ci/deploy-image.sh` in oumta-deploy decides the environment from the tag: `-dev.` goes to dev, `-beta.` to beta, anything else is skipped (prod only via PR).

Settings:

- `var` (required): variable in `envs/<env>/images.env`, e.g. `AUTH_IMAGE`. `{major}` is replaced by the major of the tag (`APP_V{major}_IMAGE` -> `APP_V2_IMAGE`).
- `deploy_token` (required): token of `oumta-ci` (`oumta_ci_token`), write access to oumta-deploy
- `registry_username`, `registry_password`: read access to the registry for the digest (`oumta-ci` with the same token)
- `envs`: fixed environments instead of the tag rule, e.g. `dev beta` (oumta-keyklo)
- `tag`: default `CI_COMMIT_TAG`
- `registry`: default `git.uesome.de`
- `image`: default `<registry>/<CI_REPO>`
- `deploy_user`: default `oumta-ci`
- `deploy_repo`: default `https://git.uesome.de/tanztee/oumta-deploy.git`

Example:

```yaml
when:
  event: tag
  ref: refs/tags/v*

steps:
  - name: build
    image: woodpeckerci/plugin-docker-buildx:6
    settings:
      registry: git.uesome.de
      repo: git.uesome.de/tanztee/oumta-auth
      tags: ${CI_COMMIT_TAG}
      build_args:
        VERSION: ${CI_COMMIT_TAG##v}
      username: oumta-ci
      password:
        from_secret: oumta_ci_token

  - name: deploy
    image: git.uesome.de/actions/ci-cd/deploy:v1.0.0
    settings:
      var: AUTH_IMAGE
      registry_username: oumta-ci
      registry_password:
        from_secret: oumta_ci_token
      deploy_token:
        from_secret: oumta_ci_token
```

### bump

Derives the next version for the pushed branch and pushes it as a tag on the triggering commit. There is no version commit: the build takes the version from the tag (`CI_COMMIT_TAG`, e.g. as build arg `VERSION: ${CI_COMMIT_TAG##v}`), `package.json` stays untouched. The tag event then starts the build.

- `release/X.Y[.Z]`, `hotfix/X.Y.Z`: next `vX.Y.Z-beta.N` of that line (D8). A hotfix needs a patch number.
- `production/*`: no bump, the step fails. A release is a retag of a beta image (D9).
- the branch in `release_branch` (repos without majors, e.g. oumta-keyklo `main`): next stable `vX.Y.Z`, the highest existing patch of the line plus one
- any other branch: `vX.Y.Z-dev.<UTC timestamp>`; the line comes from `release_line`, the branch name, the nearest `release/*` or `hotfix/*` branch (newest merge base), or `major.minor` from `package.json`

If the stable tag of a line exists (`v2.4.0` after the release), the next patch of that line is used (`v2.4.1-beta.0`, `v2.4.1-dev.…`).

Only the commit that triggered the pipeline is tagged; if the branch moved on, the step exits without a tag and the newer pipeline takes over. A commit that already carries a tag of the same kind (dev, beta or stable) is not tagged again, so a re-run does not build twice; a dev tag does not block the beta tag after a fast-forward merge.

Settings:

- `git_token` (required): token of `oumta-ci` (`oumta_ci_token`), write access to the repo
- `git_user`: default `oumta-ci`
- `release_branch`: optional, branch that gets stable tags instead of dev tags
- `release_line`: optional, `<major>.<minor>[.<patch>]`, overrides every other rule
- `remote`: default `CI_REPO_CLONE_URL`

Example:

```yaml
when:
  - event: push
    branch: ['feature/**', 'release/**', 'hotfix/**']
  - event: manual

steps:
  - name: bump
    image: git.uesome.de/actions/ci-cd/bump:v2.0.0
    settings:
      git_token:
        from_secret: oumta_ci_token
```