From 5f12fca3019c3327e0c370dfbdbeaedf4456c3e2 Mon Sep 17 00:00:00 2001
From: UltimateCoder <sayhi@ultimatecoder.dev>
Date: Thu, 15 Oct 2026 21:41:38 +0200
Subject: [PATCH] docs: add README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4e6526e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# docker-build
+
+Reusable Gitea Actions workflow: runs [replace-build-vars](https://git.custom-coding.net/templates/replace-build-vars), builds a Docker image, tags it according to the ref and pushes it.
+
+## Usage
+
+```yaml
+jobs:
+  docker:
+    uses: templates/docker-build/.gitea/workflows/docker.yaml@v1
+    with:
+      DockerImageDomain: registry.example.com
+      DockerImageOrganisation: my-org
+      DockerImageName: my-app
+      DockerImageVersion: ${{ github.ref_name }}
+      # DockerFilePath: ./Dockerfile
+    secrets:
+      DockerUsername: ${{ secrets.DOCKER_USERNAME }}
+      DockerPassword: ${{ secrets.DOCKER_PASSWORD }}
+```
+
+## Inputs / secrets
+
+| Name | Required | Default | Description |
+|---|---|---|---|
+| `DockerImageDomain` | yes | | Registry domain |
+| `DockerImageOrganisation` | yes | | Namespace in the registry |
+| `DockerImageName` | yes | | Image name |
+| `DockerImageVersion` | yes | | Value for the `VERSION` build-arg |
+| `DockerFilePath` | no | `./Dockerfile` | Path to the Dockerfile |
+| secret `DockerUsername` | yes | | Registry user |
+| secret `DockerPassword` | yes | | Registry password / token |
+
+## Tags
+
+Every build is tagged `:latest`, plus one tag based on the ref:
+
+| Ref | Tag | Pushed |
+|---|---|---|
+| `master` | `:<branch>` | yes |
+| `develop`, `feature/*` | branch with `/` → `-` | yes |
+| git tag | `:<tag>` | yes |
+| pull request | `:pr-<number>` | yes |
+| any other branch | | no (build only) |
+
+## Versioning
+
+Only major tags (`v1`, `v2`, …). Fixes move the existing tag. Changing inputs, secrets or tagging behavior needs a new major tag.
+
+History before the move: [UltimateCoder/resuable-workflows](https://git.custom-coding.net/UltimateCoder/resuable-workflows) (`@v1`–`@v3` there remain frozen).