esys-ci-host 0.1.0

Library and CLI to prepare Linux VPS hosts as GitLab CI runners

esys-ci-host

Library and CLI to prepare Linux VPS hosts as GitLab CI runners (Docker, privileged DinD, runner registration).

Extracted from the CI-host portions of esysdox-ops so LibESys superbuild and other tooling can depend on a focused package.

Install

pip install esys-ci-host

Quick start

On a fresh Ubuntu or Debian VPS (Docker executor for LibESys CI):

sudo esys-ci-host runner prepare --yes
esys-ci-host runner register --url https://gitlab.example.com --profile ci
esys-ci-host doctor

Set ESYS_CI_HOST_RUNNER_TOKEN instead of passing --token when registering.

Runner registration and executors

The GitLab executor is chosen at registration time (runner register), not during runner install or runner prepare.

Option	Purpose
--executor shell	Run jobs directly on the host (default)
--executor docker	Run jobs in containers (requires runner prepare)
--profile ci	LibESys CI preset: docker executor, privileged DinD, tags docker-privileged, and a sensible default image
--docker-image IMAGE	Override the runner’s default image (fallback only; see note below)
--docker-privileged	Privileged docker executor (enabled automatically by --profile ci)
--tags TAGS	Comma-separated runner tags (e.g. linux,docker)

Default image vs job image: GitLab Runner’s --docker-image (at register time) is only the fallback written into config.toml. Each CI job uses its own image: from .gitlab-ci.yml when present — you do not need to pass --docker-image for every image your pipeline uses. With --profile ci, a default (python:3.11-bookworm) is applied automatically; override it only if you want a different fallback for jobs that omit image:.

Shell executor (simple jobs on the host):

sudo esys-ci-host runner install --yes
esys-ci-host runner register --url https://gitlab.example.com --executor shell --tags shell

Docker executor (explicit; run prepare first). GitLab Runner requires a default image for non-interactive docker registration, so pass --docker-image here unless you use --profile ci:

sudo esys-ci-host runner prepare --yes
esys-ci-host runner register \
  --url https://gitlab.example.com \
  --executor docker \
  --docker-image python:3.11-bookworm \
  --docker-privileged \
  --tags docker-privileged

LibESys CI profile (recommended; includes docker executor defaults — no need to pass --docker-image unless overriding the fallback):

sudo esys-ci-host runner prepare --yes
esys-ci-host runner register --url https://gitlab.example.com --profile ci

Use --dry-run on runner register to print the gitlab-runner register command without executing it.

Development

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install
pre-commit install --hook-type commit-msg
pytest

Release tags vX.Y.Z must match src/esys_ci_host/__version__.py. Use make bump-release locally; CI publishes to GitLab PyPI, TestPyPI, and PyPI (manual).

License

Apache-2.0 — see LICENSE.