fix(action): build payload with jq and document that swarm mode deploys the tag

Interpolating inputs straight into the JSON string let a quote in image or
tag break the payload. Also replaces GNU-only head -n -1 so the action runs
on BSD/macOS runners.

CLAUDE.md

@@ -73,6 +73,10 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
   with a permission error against a worker-only node. This is an operator/deployment
   concern (point `DOCKER_HOST` at a manager, or schedule the updater on a manager),
   not something the code can detect or work around.
+- **`tag` is cosmetic in compose mode but load-bearing in swarm mode.** `handlers.go` folds it
+  into the requested image; compose discovery strips it via `NormaliseImage`, but
+  `SwarmExecutor` assigns it directly to `ContainerSpec.Image`. A request without a tag updates
+  a Swarm service to `:latest`.
 
 ## References
 

README.md

@@ -54,7 +54,7 @@ Two things to get right when running in Swarm mode:
 4. Point your reverse proxy (NPM/Traefik/Caddy) at `package-updater:8080`. NPM should handle TLS.
 5. `docker compose up -d`.
 6. Add the opt-in label `se.shcizo.auto-update: "true"` to each service you want auto-updated.
-7. Use the [Gitea composite action](https://gitea.shcizo.se/shcizo/package-updater-action) in your repos to call `/update` after a build.
+7. Use the [Gitea composite action](gitea-action/README.md) in your repos to call `/update` after a build.
 
 ## Configuration
 

gitea-action/README.md

@@ -0,0 +1,36 @@
+# Deploy via package-updater (composite action)
+
+Notifies `package-updater` to `docker compose pull` + `up -d` for the matching service(s) after a CI build.
+
+## Usage
+
+In a consumer repo's `.gitea/workflows/deploy.yml`:
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [build-and-push]
+    steps:
+      - uses: gitea.example.com/shcizo/package-updater/gitea-action@v1
+        with:
+          endpoint: https://updater.example.com/update
+          image: registry.example.com/${{ gitea.repository }}
+          tag: ${{ gitea.sha }}
+          token: ${{ secrets.UPDATER_TOKEN }}
+```
+
+`UPDATER_TOKEN` should be set as an organisation-level secret in Gitea so all repos share it.
+
+## Inputs
+
+| Name | Required | Default | Description |
+|---|---|---|---|
+| `endpoint` | yes | — | Full URL to `/update` |
+| `image` | yes | — | Image reference without tag |
+| `tag` | no | `""` | Tag that was just pushed. Compose mode ignores it (the compose file pins the reference); **swarm mode sets the service image to it**, so omitting it deploys `:latest`. Always pass it. |
+| `token` | yes | — | Bearer token configured in package-updater |
+
+## Failure modes
+
+The step exits non-zero if `package-updater` returns HTTP 4xx or 5xx. This is intentional — the workflow surfaces the deploy failure to whoever pushed.

gitea-action/action.yml

@@ -0,0 +1,46 @@
+name: "Deploy via package-updater"
+description: "Notifies package-updater to pull & restart a Docker Compose service"
+inputs:
+  endpoint:
+    description: "Full URL to /update (e.g. https://updater.example.com/update)"
+    required: true
+  image:
+    description: "Image reference without tag (e.g. registry.example.com/myapp)"
+    required: true
+  tag:
+    description: "Tag that was just pushed. Required in practice for swarm instances — it becomes the image the service is set to. Omit it and swarm deploys :latest."
+    required: false
+    default: ""
+  token:
+    description: "Bearer token for package-updater"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Trigger update
+      shell: bash
+      env:
+        ENDPOINT: ${{ inputs.endpoint }}
+        IMAGE: ${{ inputs.image }}
+        TAG: ${{ inputs.tag }}
+        TOKEN: ${{ inputs.token }}
+      run: |
+        set -euo pipefail
+        # Build the payload with jq so quotes or backslashes in the inputs
+        # cannot break out of the JSON string.
+        payload=$(jq -nc --arg image "$IMAGE" --arg tag "$TAG" \
+          '{image: $image, tag: $tag}')
+        response=$(curl -sS -w "\n%{http_code}" \
+          -X POST "$ENDPOINT" \
+          -H "Authorization: Bearer $TOKEN" \
+          -H "Content-Type: application/json" \
+          -d "$payload")
+        # Split on the last newline: curl's -w appended the status code
+        # there. Pure bash — `head -n -1` is GNU-only and fails on BSD/macOS.
+        code="${response##*$'\n'}"
+        body="${response%$'\n'*}"
+        echo "HTTP $code"
+        printf '%s' "$body" | jq . || printf '%s\n' "$body"
+        if [ "$code" -ge 400 ]; then
+          exit 1
+        fi