Update READMEs, add pause on failure for debugging

README.md

@@ -11,18 +11,23 @@ In the garm project edit the file deploy.yaml:
 
 Use these commands in the current project.
 
-´´´bash
+```bash
 docker buildx build -t edp.buildth.ing/devfw-cicd/garm:provider-ec-[new_number] --push .
 
 kubectl apply -f ../garm/deploy.yaml
-´´´
+```
 
 Don't forget to rebuild the ubuntu-host-runner if anything changed in the `runner` folder:
 
-```
+```bash
 docker buildx build --platform linux/amd64 --push -t edp.buildth.ing/devfw-cicd/ubuntu-host-runner:latest runner
+docker buildx build --platform linux/amd64 --push -t edp.buildth.ing/devfw-cicd/ubuntu-host-runner:$(date +"%Y-%m-%d-%H%M") runner
 ```
 
+# Updating GARM
+
+Information on resetting GARM can be found in the [runner/ README](/runner/README.md).
+
 # Configuration
 
 ## Extra Specs
@@ -111,9 +116,3 @@ volumes:
   - name: runner-dir
     emptyDir: {}
 ```
-
-## Build the runner on macos
-
-```
-cd runner && docker buildx build --platform linux/amd64 --push -t edp.buildth.ing/devfw-cicd/ubuntu-host-runner:$(date --utc --iso-8601) . && cd -
- ```

runner/Dockerfile

@@ -6,4 +6,7 @@ RUN curl https://edp.buildth.ing/DevFW-CICD/runner/releases/download/v11.3.3/run
 
 COPY ./entrypoint.sh /entrypoint.sh
 
+LABEL org.opencontainers.image.description="Custom GARM provider for Edge Connect. Built from \
+https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect/src/branch/main/runner"
+
 ENTRYPOINT [ "/entrypoint.sh" ]

runner/README.md

@@ -0,0 +1,49 @@
+# GARM runner for Edge Connect
+
+Note that the primary README for this resource is in the [root directory](/README.md) of this repository. Further information may be found in the [project documentation](https://docs.edp.buildth.ing/docs/).
+
+## Deployment
+
+These steps can be used to set up a GARM instance on a (relatively) clean Forgejo EDP cluster.
+
+### Assumptions
+The following steps assume:
+- You are working on a running Forgejo called `garm-provider-test` (and accessible at https://garm-provider-test.t09.de)
+    - The cluster should be deployed via the [infra-deploy workflow](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml&actor=0&status=0)
+    - If a new cluster doesn't behave like the existing one, its [config](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/95904c87f0c7248d418d7ed1dc6754d81fc4cccc/non-prod) may differ from [garm-provider-test](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/95904c87f0c7248d418d7ed1dc6754d81fc4cccc/non-prod/garm-provider-test)'s
+- You have access to the kubernetes cluster via `kubectl` / `k9s`
+    - The relevant Kubeconfig can be downloaded from the [OTC console](https://auth.otc.t-systems.com/authui/federation/websso?domain_id=81e7dbd7ec9f4b03a58120dfaa61d3db&idp=ADFS_MMS_OTC00000000001000113497&protocol=saml): Left menu -> Containers -> Cloud Container Engine -> \<cluster\> -> CLI tool (top right corner) -> Public access -> \<copy yaml, paste locally\>
+- The [Forgejo](https://garm-provider-test.t09.de) has two repositories, [demo_dummy](https://garm-provider-test.t09.de/giteaAdmin/demo_dummy) and [demo_docker](https://garm-provider-test.t09.de/giteaAdmin/demo_docker)
+    - These can be recreated from scratch if lost. The former has a workflow that just runs for 30 seconds then stops; the latter runs `docker/build-push-action@v6` on a trivial Dockerfile.
+
+### Steps
+1. Kill `garm` PVC in `garm-provider-test` cluster
+1. Kill `garm` pod in `garm-provider-test` cluster
+1. Sync ArgoCD (http://argocd.garm-provider.test.t09.de/) to recreate PVC
+- Garm should now (after a minute or two) be available with no config
+    - this is because each Helm chart deploy recreates the db passphrase
+    - this isn't easy to fix because ArgoCD [doesn't support](https://github.com/argoproj/argo-cd/issues/21745) using [lookup](https://edp.buildth.ing/DevFW-CICD/garm-helm/src/commit/b46e1d03b5ab58558d5677e2df0c20b970e9ac3d/charts/garm/templates/secrets.yaml#L18) to read a persistent secret
+1. Log into [garm](https://garm.garm-provider-test.t09.de/) using admin / password found in garm-credentials secret on garm-provider-test cluster
+1. Set up Garm in this order:
+    - Endpoint
+        - URL: `https://garm-provider-test.t09.de/`
+        - API endpoint: `https://garm-provider-test.t09.de/api/v1`
+    - Credentials
+        - Type: Gitea
+        - PAT: persistent, read from password manager if desired
+    - Repository
+        - Type: Gitea
+        - Repo name: [demo_dummy](https://garm-provider-test.t09.de/giteaAdmin/demo_dummy) or [demo_docker](https://garm-provider-test.t09.de/giteaAdmin/demo_docker)
+        - Owner: giteaAdmin
+        - (Create Webhook fails with error 500, this is not a problem)
+            - this is because forgejo [currently deployed](https://edp.buildth.ing/DevFW-CICD/stacks-instances/src/commit/63cd12e7fd9e351b536b868f3c2d35a1e81dae6d/otc/garm-provider-test.t09.de/stacks/forgejo/forgejo-server/values.yaml#L177) contains support for ephemeral runners but not webhooks
+            - ideally these two features will be merged upstream, then forgejo can be updated to the upstream version
+    - Pool
+        - Entity: repo
+        - Provider: edge-connect
+        - Image: `edp.buildth.ing/devfw-cicd/ubuntu-host-runner:2025-11-03-c` [or more recent](https://edp.buildth.ing/DevFW-CICD/-/packages/container/ubuntu-host-runner/)
+        - Flavor: EU.small (but not actually read)
+        - Min idle runners: 1 (if testing is desired)
+        - Tags: [ubuntu-latest](https://garm-provider-test.t09.de/giteaAdmin/demo_dummy/src/branch/main/.forgejo/workflows/example.yaml#L9)
+    - Runner
+        - should be automatically created by/in the Pool

runner/entrypoint.sh

@@ -52,9 +52,17 @@ function call() {
     curl --retry 5 --retry-delay 5 --retry-connrefused --fail -s -X POST -d "${PAYLOAD}" -H 'Accept: application/json' -H "Authorization: Bearer ${BEARER_TOKEN}" "${cb_url}" || echo "failed to call home: exit code ($?)"
 }
 
+set +e
 # retrieve runner secret from garm
 RUNNER_SECRET=$(curl --retry 5 --retry-delay 5 --retry-connrefused --fail -v -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${BEARER_TOKEN}" "${METADATA_URL}/runner-registration-token/")
 
+if [ -z "$RUNNER_SECRET" ]; then
+    echo Failed to retrieve runner secret from GARM >&2
+    sleep 30
+    exit 1
+fi
+set -e
+
 forgejo-runner \
     register \
     --no-interactive \