wanjakrah/engineering
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

S19: share workstation runner and move agent workflows to landscape

Browse Source
This commit is contained in:
Wanja Krah
2026-11-10 08:14:35 +01:00
parent c25ce11a1b
commit 46df72f008
40 changed files with 334 additions and 498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@@ -1,9 +1,9 @@
# Engineering
Versioned skills, Java standards, formatting, coverage checks, and the Gitea
Versioned Java standards, formatting, coverage checks, and the Gitea
Actions / Maven Java 25 / npm / Docker Compose recipe. Architecture and
specifications belong to [landscape](http://192.168.2.28:3000/wanjakrah/landscape).
Source attribution is in SOURCE.md; upstream skill licenses accompany each skill.
Shared agent skills are maintained in landscape under skills/. Source attribution is in SOURCE.md.
## Start a project
@@ -11,7 +11,7 @@ Clone this repository and check out a released tag. Use JDK 25, Maven, Python 3,
Git, Docker with Compose, and a supported Node version for a frontend.
```sh
python3 create-project.py my-project ../my-project --version v1.0.0 --components both --runner engineering
python3 create-project.py my-project ../my-project --version v2.0.0 --components both
```
Choose `backend`, `frontend`, or `both`. The command refuses existing destinations
@@ -21,8 +21,11 @@ while preserving the configured build commands and container contracts.
Initialize the resulting Git repository and commit its generated resources.
Create the remote repository separately, configure its runner and secrets, then
push. The runner label must match an available **host** runner with the required
tools. `--runner` deliberately has no machine-specific default.
push. New projects default to the shared **host** runner label `mini-pc`.
Register it once at Gitea user scope for the owner of the projects; it then serves
existing and future repositories of that owner. `--runner` overrides the label for
another workstation. A label alone does not grant a repository access to a runner.
Do not install another runner service for every project.
## Consumer layout and configuration
@@ -88,11 +91,58 @@ Manual deployment and rollback workflows require variables `DEPLOY_HOST`,
a successful main-push build.yaml run. Keep build.yaml's filename when adapting
the recipe. Configure Gitea access, registry access and SSH host trust explicitly.
Runner setup mechanisms are available as `configure-gitea`, `configure-docker`
and `install-runner`. Supply GITEA_SERVER_URL, CI_REPOSITORY, RUNNER_LABEL and
INSECURE_REGISTRY where applicable; the latter is only for a deliberately trusted
internal HTTP registry. Runner configuration and service templates are project
files under ci/runner/. Installation currently supports Linux x86_64 host runners.
### Shared workstation runner
Set up the physical mini-pc once, using a consumer generated from this release:
```sh
export GITEA_SERVER_URL=http://192.168.2.28:3000
export RUNNER_NAME=mini-pc
export RUNNER_LABEL=mini-pc
export RUNNER_SCOPE=user
# Owner-only PAT file with permissions for the selected runner scope; never a workflow secret.
export GITEA_ADMIN_TOKEN_FILE="$HOME/.config/mini-pc-runner/admin-token"
java generated/ci/Ci.java configure-runner
java generated/ci/Ci.java install-runner
systemctl --user status mini-pc-runner
```
User scope uses `/api/v1/user/actions/runners/registration-token`, granting the
runner access to that user's current and future repositories. Organization and
instance scopes are optional alternatives (`RUNNER_ORGANIZATION` is required for
organization scope); instance scope requires a Gitea administrator. Repository
scope is available only for intentionally isolated runners. For this landscape,
use user scope for `wanjakrah` and the label `mini-pc`.
The runner has one slot shared by all projects. Its identity, service and state
are based on RUNNER_NAME, independent of PROJECT_NAME: `~/.local/share/mini-pc-runner`,
`~/.config/mini-pc-runner` and `mini-pc-runner.service`. Application credentials remain
in each application's secrets; never copy deployment credentials into runner defaults.
The host runner executes trusted project code as the workstation user; use it for
repositories maintained by the trusted owner. A new project's first push needs no
new workstation registration. Ensure the workstation is awake and Docker is ready.
For each new repository enable Actions, configure its own registry secrets and
TARGET_PLATFORM, then verify availability before pushing:
```sh
export CI_REPOSITORY=wanjakrah/my-project
# Owner PAT with read access to the repository, user profile and user runners.
java generated/ci/Ci.java check-runner
```
`configure-gitea` configures the application and does not create runner registrations.
`configure-runner` obtains the one-time shared registration token; `install-runner`
installs and registers the workstation. `--prepare-only` installs without registering
or starting. Installation supports Linux x86_64. `configure-docker` uses
INSECURE_REGISTRY only for a deliberately trusted internal HTTP registry.
Runner configuration and service templates are under ci/runner/.
When migrating a repository-scoped runner, keep the old registration and service
available until the new shared runner is online and has run a test workflow for
both an existing and a new consumer. Change all workflow labels to `mini-pc`, then
stop/disable the old service. Preserve its state outside Git for recovery. Do not
change application-specific deployment credential paths as part of this migration.
## Deployment and recovery