Skip to content
RealHW

GitLab event onboarding

GitLab job events create durable demand that can start cold RealHW capacity. A runner registration alone does not establish event delivery. CLI 0.4.0 adds the commands below; check realhw capabilities --json for server support before applying changes. A 404 means the matching API has not been deployed. The retired Rust CLI has no onboarding support; use the Python realhw-cli repository.

Customer workflow

Section titled “Customer workflow”

Use an existing runner UUID from realhw runners list --account-id ACCOUNT_UUID. Inspection requires runners:read; configuration requires runners:write and the registration’s account/project scope. Browser login defaults to read-only permissions. Request the necessary permissions explicitly or provision a restricted API key.

Terminal window
realhw capabilities --json
realhw runners webhook inspect RUNNER_UUID --json
realhw runners webhook configure RUNNER_UUID --reason 'Enable pending-job demand' --json
realhw runners webhook configure RUNNER_UUID --reason 'Enable pending-job demand' --apply --json

Configure defaults to preview: it reads GitLab but does not create/update a hook or persist a supplied credential. It records an audit operation, including previews and failures. Review the callback, action, blockers, and limitations before applying. An apply creates one hook or updates the existing exact-callback hook in place. Multiple matching hooks block the operation; unrelated hooks are left intact.

If the registration has no usable stored project API credential, inject a token from your secret manager into an environment variable, then name that variable:

Terminal window
realhw runners webhook configure RUNNER_UUID --reason 'Restore project event delivery' \
  --gitlab-token-env PROJECT_GITLAB_TOKEN --json
realhw runners webhook configure RUNNER_UUID --reason 'Restore project event delivery' \
  --gitlab-token-env PROJECT_GITLAB_TOKEN --apply --json

Never put the token value in an argument, prompt, JSON file, or documentation. GitLab requires project read access and sufficient API permissions/role to manage hooks (normally Maintainer). Successful apply encrypts the supplied project credential for subsequent job metadata reads. Failed apply and preview do not replace it. Tokens are never returned. Use the narrowest project-scoped token GitLab supports.

Operator workflow

Section titled “Operator workflow”

Set REALHW_OPS_API_BASE and REALHW_OPS_TOKEN through your approved secret environment. Ops commands never fall back to customer credentials and read the Ops policy before webhook operations.

Terminal window
realhw ops policy --json
realhw ops runners webhook inspect RUNNER_UUID --json
realhw ops runners webhook configure RUNNER_UUID --reason 'Restore event onboarding' --json
realhw ops runners webhook configure RUNNER_UUID --reason 'Restore event onboarding' --apply --json

The customer endpoints are GET and POST /api/v1/virtual-runners/{runner_id}/gitlab-webhook. Typed Ops equivalents use /admin/realhw/virtual-runners/{runner_id}/gitlab-webhook. POST accepts reason, dry_run (defaults true), and optional write-only gitlab_access_token. Configure returns operation_id, dry_run, action (create or reconcile), and status. Rust DTOs generate the browser contract; the Python client preserves the API JSON.

Delivery and recovery

Section titled “Delivery and recovery”

RealHW derives a per-project hook verifier from its server-only root. Only the derived verifier goes to that project’s GitLab instance. The receiver continues accepting retained legacy verifiers during migration. The callback is derived from the trusted server REALHW_GITLAB_WEBHOOK_ORIGIN HTTPS origin, never from a request Host header. The dashboard origin may be IP restricted and must not be used here. Operators must ensure that the configured public API origin routes /api/v1/gitlab/webhooks/ to this API.

A successful configuration means provider readback verified the hook identity, job and pipeline subscriptions, enabled status and TLS verification. GitLab versions may omit token_present; verification_token_present: null remains unknown. Configuration is not evidence that an event arrived or that a job ran. provider_inspected: false means hook presence is unknown; an empty hooks array in that state proves nothing.

After applying, trigger an authorized real pipeline and verify retained demand for that project, scheduling, and a running job. last_demand_received_at is historical, not proof of current delivery. Do not cancel productive jobs just to generate events. After a timeout, inspect first: an external GitLab write may have completed even if RealHW could not finish its database transaction. The retained audit intent records that uncertainty; rerunning reconciliation uses the same exact callback identity.

Developers: run API provider/receiver tests, isolated PostgreSQL scope/audit tests, CLI contract tests, typeshare, and the docs build. Do not validate against production by creating arbitrary hooks or writing credentials to disk.