feat: add resolve-buildx-cache as a shared composite action

README.md

@@ -0,0 +1,67 @@
+# gitea-runner/actions
+
+Współdzielone composite actions do jobów Gitea Actions na `git.cierzniak.it`.
+
+Jedna akcja = jeden podkatalog. Repo może zostać prywatne — runner uwierzytelnia się
+przy pobieraniu akcji, patrz „Dostęp" niżej.
+
+## Akcje
+
+| Akcja | Do czego |
+| --- | --- |
+| [`resolve-buildx-cache`](resolve-buildx-cache/) | `DOCKER_CACHE_*` z runnera → `driver-opts` i refy cache'a dla buildx |
+
+## Jak używać
+
+Pełny URL w `uses:` i **tag**, nigdy `@main`:
+
+```yaml
+      - name: Resolve buildx cache settings
+        id: cache
+        uses: https://git.cierzniak.it/gitea-runner/actions/resolve-buildx-cache@v1
+        with:
+          cache-image: ${{ github.repository }}/app
+```
+
+Pełny URL jest konieczny, bo `DEFAULT_ACTIONS_URL` tej instancji wskazuje na GitHuba —
+`uses: gitea-runner/actions/...@v1` poleciałoby tam i padło. Przestawianie tego ustawienia
+na `self` jest odradzane przez dokumentację Gitei, bo wymusiłoby mirrorowanie lokalnie także
+`actions/checkout` i całej reszty.
+
+Tag zamiast gałęzi, ponieważ jedno repo obsługuje wiele pipeline'ów: push do `main`
+przy `@main` zmieniłby je wszystkie naraz.
+
+## Dostęp
+
+Organizacja `gitea-runner` jest `limited`, więc anonimowy `git clone` tego repo nie działa.
+To **nie** jest przeszkoda: `act_runner` pobiera akcje z tokenem
+(`GoGitActionCache.Fetch` → `http.BasicAuth{Username: "token", Password: token}`).
+
+Żeby ten token był autoryzowany, każde repo-konsument musi mieć tu nadany dostęp:
+
+> **Settings → Actions → General → collaborative owners** — dodaj *właściciela*
+> (organizację albo użytkownika), nie pojedyncze repo.
+
+Bez tego job pada przy rozwiązywaniu `uses:`, jeszcze przed pierwszym krokiem akcji.
+Ustawienia nie ma w REST API — trzeba wyklikać.
+
+Aktualnie nadane: `cierzniak-it`.
+
+Kandydaci do dodania, gdy akcja pojedzie szerzej (repo z buildxem w CI):
+`leczenieran` (`wizytowka`, `elektroniczna-dokumentacja-medyczna`),
+`welding-technology-review` (`witryna-internetowa`), `ekoinbud` (`production-system`).
+
+## Wersjonowanie
+
+`vN` to **ruchomy** tag majora — poprawki i wstecznie zgodne zmiany przesuwają go na nowy
+commit, konsumenci nie ruszają swoich workflow. Zmiana łamiąca kontrakt (usunięty input,
+zmieniona semantyka outputu) dostaje `vN+1`, a stary tag zostaje tam, gdzie stał.
+
+Po przesunięciu tagu: `git tag -f vN && git push -f origin vN`. Runner rozwiązuje ref przy
+każdym jobie, więc konsumenci łapią zmianę bez żadnej akcji po swojej stronie — to samo
+zdanie czyta się też jako ostrzeżenie o zasięgu rażenia.
+
+## Powiązane repo
+
+- [`gitea-runner/images`](https://git.cierzniak.it/gitea-runner/images) — obrazy bazowe
+  jobów, ADR-y i przykłady workflow.