Runners

Purposes & integrations

purpose and integration_type are independent enums — github_actions, gitlab_runner, agent, generic, and the job-source grant each one needs

Every runner group stores a purpose (the workload) and an integration (the job source the binary registers with). Backend kind is orthogonal — any production backend can host CI or agents, as long as purpose matches the work.

The create wizard at runners.orkestia.dev exposes two workload buttons (CI jobs / Agent sessions) and, for CI, an integration picker (GitHub / GitLab / None). It then writes both enums so they stay consistent.

Purposes

`purpose`	Written when	Hosts	Eligibility
`github_actions`	CI jobs + GitHub integration	Self-hosted GitHub Actions runners	GitHub `runs-on` labels on the group
`gitlab_runner`	CI jobs + GitLab integration	GitLab Runner registration against a GitLab connection	GitLab job tags
`generic`	CI jobs + no job-source integration	Command / workflow executions with no GitHub or GitLab registration	Callers of `runner.execution-launch-generic` (and backend variants)
`agent`	Agent sessions	Staff / coding agent sessions in your cloud (or DevKit)	Only this value is agent-eligible

agent-eligible := (purpose == agent)

config.supports_agents is enablement (this group may appear in a picker). It does not convert a github_actions or generic group into an agent pool. Create the group as an agent pool from the start. Details: Agent runner groups.

Integrations

`integration_type`	Grant required	Typical purpose
`github`	GitHub App installation on the org	`github_actions`
`gitlab`	GitLab cloud connection	`gitlab_runner`
`none`	None	`agent` or `generic`

Agent purpose forces none. A GitLab-integrated group sets gitlab_runner. A GitHub-integrated CI group sets github_actions. A CI group with no job source sets generic.

GitLab is a first-class integration in the create wizard and in RunnerIntegrationType. It is not the same as “GitHub Actions only” copy on older pages. GitHub remains the GA job source for most fleets; GitLab groups need a working GitLab connection before the wizard will let you pick it.

Combinations the wizard writes

Workload choice	Integration choice	Stored `purpose`	Stored `integration_type`
CI jobs	GitHub	`github_actions`	`github`
CI jobs	GitLab	`gitlab_runner`	`gitlab`
CI jobs	None	`generic`	`none`
Agent sessions	(forced none)	`agent`	`none`

Do not point a Staff actor config at a github_actions / gitlab_runner / generic group. Session-launch fails fast with a not-agent-eligible error.

Job routing

GitHub. Orkestia mints a short-lived registration token via the GitHub App. The runner binary registers itself and picks up jobs whose runs-on matches the group's labels. See Runner management.

GitLab. The group references gitlab_connection_uuid. The runner registers with that GitLab instance. Tags on the group are the GitLab equivalent of GitHub labels.

None. Nothing phones home to a CI product. Executions are launched as generic commands or as agent sessions, depending on purpose.

DevKit