From e6b9d99305a23a0cdf3590c9206d187448228e76 Mon Sep 17 00:00:00 2001
From: Jose Henrique <jose.henrique.ivan@gmail.com>
Date: Mon, 13 Jul 2026 19:49:47 -0300
Subject: [PATCH] docs: add job name: to all usage snippets + rule requiring
 named jobs

---
 AGENTS.md |  1 +
 README.md | 46 +++++++++++++++++++++++-----------------------
 2 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e3849ab..366c1de 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -124,6 +124,7 @@ Consumer projects must set these secrets in Gitea repo settings (Settings → Ac
 ## Rules
 
 - Pin composite action refs to `@main` until version tags are created.
+- Every job **must** have a `name:` field (e.g. `name: Build Image`, `name: Deploy (internal)`). Unnamed jobs render as their raw ID (`build`, `deploy`, …) in the Gitea Actions UI and run logs. The workflow template above includes `name:` on every job — copy it as-is.
 - Always use the full URL `https://git.ivanch.me/ivanch/pipeline-actions/<action>@main` for `uses:` — Gitea cannot resolve the bare GitHub-style `ivanch/pipeline-actions/...` path.
 - Always use `runs-on: ubuntu-amd64` (homelab Gitea runner label).
 - Always build `linux/amd64,linux/arm64` — the cluster has mixed arch (iris+vega=amd64, nebula+nexus=arm64).
diff --git a/README.md b/README.md
index aac9022..18b13aa 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ Builds and pushes a multi-architecture Docker image using a remote Buildx builde
 ```yaml
 jobs:
   build:
+    name: Build Image
     runs-on: ubuntu-amd64
     steps:
       - uses: actions/checkout@v4
@@ -35,13 +36,6 @@ jobs:
 | `image` | ✅ | — | Full image reference without tag |
 | `registry_password` | ✅ | — | Registry password/token (use secrets) |
 | `ssh_key` | ✅ | — | SSH private key for the remote builder (use secrets) |
-| `image_tag` | ❌ | `latest` | Comma-separated tag(s) to apply to the built image (e.g. `latest,abc1234`). Pushing a commit-pinned tag alongside `:latest` is how Docker-only deploys consume per-commit tags. |
-| `registry_host` | ❌ | `git.ivanch.me` | Container registry hostname |
-| `registry_username` | ❌ | `ivanch` | Registry username |
-| `platforms` | ❌ | `linux/amd64,linux/arm64` | Target build platforms |
-| `build_context` | ❌ | `.` | Docker build context |
-| `build_dockerfile` | ❌ | `Dockerfile` | Dockerfile path |
-| `build_args` | ❌ | _(empty)_ | Build arguments, one `KEY=VALUE` per line; each becomes a `--build-arg` |
 | `docker_host` | ❌ | `docker-build.haven` | Remote builder hostname |
 | `docker_user` | ❌ | `root` | SSH user for remote builder |
 
@@ -51,21 +45,6 @@ jobs:
 
 Validates a kubeconfig, installs kubectl, and performs a `rollout restart` of a Kubernetes Deployment.
 
-```yaml
-jobs:
-  deploy:
-    runs-on: ubuntu-amd64
-    needs: build
-    steps:
-      - uses: https://git.ivanch.me/ivanch/pipeline-actions/deploy-restart@main
-        with:
-          kube_config: ${{ secrets.KUBE_CONFIG }}
-          deployment_name: my-app
-          # optional:
-          # namespace: default
-          # kube_version: stable
-```
-
 | Input | Required | Default | Description |
 |---|---|---|---|
 | `kube_config` | ✅ | — | Full kubeconfig YAML (use secrets) |
@@ -80,6 +59,7 @@ Validates a kubeconfig, installs kubectl, and applies Kubernetes manifest(s) tha
 ```yaml
 jobs:
   deploy:
+    name: Apply Manifests (internal)
     runs-on: ubuntu-amd64
     needs: build
     steps:
@@ -103,6 +83,22 @@ jobs:
 
 > At least one of `manifest` or `manifests` must be set; a missing file fails the step (the manifest must live in the repo).
 
+```yaml
+jobs:
+  restart:
+    name: Rollout Restart (internal)
+    runs-on: ubuntu-amd64
+    needs: apply
+    steps:
+      - uses: https://git.ivanch.me/ivanch/pipeline-actions/deploy-restart@main
+        with:
+          kube_config: ${{ secrets.KUBE_CONFIG }}
+          deployment_name: my-app
+          # optional:
+          # namespace: default
+          # kube_version: stable
+```
+
 ---
 
 ### `ssh-deploy`
@@ -112,6 +108,7 @@ SSH into a remote host and run `docker compose pull` + `docker compose up -d --f
 ```yaml
 jobs:
   deploy:
+    name: SSH Deploy (internal)
     runs-on: ubuntu-amd64
     needs: build
     steps:
@@ -141,7 +138,10 @@ jobs:
 
 ---
 
-## Required Secrets
+## Rules
+
+- Every job **must** have a `name:` field (e.g. `name: Build Image`, `name: Deploy (internal)`). Named jobs make the Gitea Actions UI and run logs readable — unnamed jobs show up as the raw job ID (`build`, `deploy`, …). The templates above all include `name:`.
+- Pin composite action refs to `@main` until version tags are created.
 
 Consumer repositories need these secrets configured in Gitea: