From a953ce334dbc6ebbfc1a6ad1ba6169e0538c0b5b Mon Sep 17 00:00:00 2001 From: mgrani Date: Wed, 15 Jul 2026 19:22:27 +0200 Subject: [PATCH] docs: describe on-demand CI runner workflow The 'owseu runner' project runner is started manually with gitlab-runner run instead of running as a permanent service; document start/stop, pending-pipeline behavior while offline, and how to register a runner on a new machine. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_0196bRzaYxjC3Mfr14UXUkBA --- .agent/workflows/release.md | 10 ++++++++-- docs/source/dev.md | 15 ++++++++++++++- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/.agent/workflows/release.md b/.agent/workflows/release.md index ac108d1..ff298db 100644 --- a/.agent/workflows/release.md +++ b/.agent/workflows/release.md @@ -42,12 +42,18 @@ Typing a version tag (`v*`) triggers the `publish-package` pipeline which: - Builds the wheel/sdist - Publishes to the GitLab Package Registry -All CI jobs carry the tag `owseu runner` (set in the `default:` block of `.gitlab-ci.yml`) and are executed by the project's docker-executor runner registered under that tag. +All CI jobs carry the tag `owseu runner` (set in the `default:` block of `.gitlab-ci.yml`) and are executed by the project's docker-executor runner registered under that tag. The runner is started **on demand** on the runner host — it is not a permanent service: + +```bash +gitlab-runner run # start polling (foreground); Ctrl+C to stop when the pipeline is done +``` + +Pipelines pushed while the runner is offline simply queue as *pending* and start once the runner is up. ## Troubleshooting ### Pipeline stuck in pending -The pipeline runs on the project runner tagged `owseu runner`. If jobs stay pending, verify the runner is online (Project → Settings → CI/CD → Runners) and its tag matches the jobs' tag. Note that a pipeline always uses the `.gitlab-ci.yml` of the commit it was created from — changing tags in a later commit does not unstick an existing pipeline; re-point the version tag or re-run from a new commit. +The pipeline runs on the project runner tagged `owseu runner`, which must be started manually (`gitlab-runner run` on the runner host). If jobs stay pending with the runner online, verify (Project → Settings → CI/CD → Runners) that its tag matches the jobs' tag. Note that a pipeline always uses the `.gitlab-ci.yml` of the commit it was created from — changing tags in a later commit does not unstick an existing pipeline; re-point the version tag or re-run from a new commit. ### Dependency Conflicts If `uv lock` fails due to conflicting URLs (e.g. `py4lexis` vs `python-http-irods-client`): diff --git a/docs/source/dev.md b/docs/source/dev.md index 42a2beb..9bd699c 100644 --- a/docs/source/dev.md +++ b/docs/source/dev.md @@ -129,7 +129,20 @@ The `publish-package` CI job triggers automatically on version tags (`v*.*.*`) a - Builds the package with `uv build` - Publishes to GitLab Package Registry -**Runner requirement**: All CI jobs are tagged `owseu runner` (see the `default:` block in `.gitlab-ci.yml`) and run on the project's docker-executor runner registered under that tag. If a pipeline sits in *pending*, check that the runner is online (Project → Settings → CI/CD → Runners) and that its tag still matches; on the runner host, the `gitlab-runner` service must be running and its user able to access the Docker daemon. +**Runner requirement**: All CI jobs are tagged `owseu runner` (see the `default:` block in `.gitlab-ci.yml`) and run on the project's docker-executor runner registered under that tag. + +The runner is **not** running as a permanent service — it is started on demand on the runner host: + +```bash +# Start the runner (foreground; uses ~/.gitlab-runner/config.toml) +gitlab-runner run + +# Stop it again with Ctrl+C once the pipeline is done +``` + +While the runner is offline, pipelines queue as *pending* and are picked up as soon as the runner starts — so the order of pushing a tag and starting the runner does not matter. If a pipeline stays *pending* even with the runner online, check (Project → Settings → CI/CD → Runners) that the runner's tag still matches the jobs' `owseu runner` tag, and that the user running `gitlab-runner` can access the Docker daemon (`docker info`). + +To register a runner on a new machine: create a project runner under Project → Settings → CI/CD → Runners (set the tag `owseu runner`), then on the machine run `gitlab-runner register --url https://opencode.it4i.eu --token ` choosing the `docker` executor and any default image (e.g. `python:3.12`). ### Pre-Release Checklist 1. **Verify Dependencies**: -- 2.51.2