Skip to content

Run CI/CD against TOVIO

Your pipelines don't need a separate set of credentials with the keys to everything. In TOVIO, a CI runner is an agent: it authenticates with a scoped capability token, not a human login, and builds against exactly the files that token allows. A leaked token is bounded by its scope, and every build it runs is in the audit log.

This guide shows how to think about CI on TOVIO, what a runner's token can reach, and how the GitHub Actions / Spacelift integrations fit in.

What works today vs. what's coming

The capability-token model a runner uses is built. The reference GitHub Actions and Spacelift bridges that wire those tokens into a hosted pipeline (@tovio/ci-bridge: one Node wrapper core behind a GitHub Action and a Spacelift hook, plus an exact-version setup action) are built in-tree on the CI/CD compatibility track (DX-017), but their Marketplace listing and publication evidence are still open Phase 5 items. TOVIO provides the auth-and-scope compatibility layer; it is not a CI runner itself today — you keep your existing CI system and point it at a TOVIO repo.

This is the accurate framing, and it is why the CI/CD guide opens with a notice that no execution substrate is provisioned: TOVIO models and gates pipelines, but nothing in the product executes a job yet.

The idea: a runner is a scoped agent

In Git-based CI, a runner usually holds a broad token that can read the whole repo. On TOVIO, you issue the runner its own capability token scoped to just the paths it needs to build:

# A runner token: excluded from every protected path, expiring in 2 hours
tovio agent new ci-build \
  --model "ci:runner" \
  --task "build and test" \
  --expires-in 2

You do not hand the runner a path glob. The issuer derives the token's reach for you, and that is the point:

  • Every policy-protected path is excluded, automatically. agent new issues path_scope = ** with denied_path_scope set to every protected path in the policy manifest. A protected path is refused at the scope stage, before TOVIO looks at the encryption envelope, so a refusal leaks neither the file nor which policy guards it. There is no per-runner glob to get wrong, and no way to widen the token by mistyping one.
  • No secret clearance, ever, from this command. The issued token carries secret_clearance: false, so the runner works against the readable subset and cannot decrypt policy-protected files. Clearance is an attribute of a human identity the Key Authority authorizes, not a flag on a runner token.
  • Writes land in the agent's own namespace. The token's branch scope is agent/ci-build/**, so a runner cannot write to a protected lane even if its build script tries.

The scope is not yours to narrow

An earlier version of this page taught --scope "src/**" and --clearance. Neither flag exists. A runner reads all clear code in the repository; what it cannot reach is anything a policy protects. If a build must not read src/vendor/**, the way to enforce that is a policy on that path, not a token flag.

Hand the token to your runner with tovio agent token <token-id>, and revoke it any time with tovio agent revoke <token-id> — revoking a token invalidates its whole delegated sub-tree at once. For a hosted runner that should not hold a long-lived token at all, tovio agent session export produces a passphrase-encrypted bundle, and tovio agent session oidc exchanges a provider workload OIDC token for a short-lived session instead.

Triggering builds: events and required checks

An on-premise Forge emits events your CI subscribes to, so the pipeline triggers on the right moments and its result becomes a gate:

  • change.proposed → run your checks against the proposed change.
  • change.landed → run your deploy.
  • A passing CI result posts back as a required check that lane protection consumes — a change can't land onto a protected lane until the check is green, the same way you'd gate a merge today.

Events and required checks ship with the Forge

Phase 3 event cursors/SSE, webhooks, and required-check posting are implemented in the Forge. TOVIO deliberately does not yet ship its own hosted CI execution service; existing runners consume these integration surfaces.

GitHub Actions & Spacelift

You don't have to leave your current CI platform. The compatibility layer lets a runner on GitHub Actions or Spacelift authenticate to a TOVIO remote with a scoped token and run your existing workflow — so a team that migrated its repo (or is running a Git bridge) keeps its pipelines instead of rewriting them.

The model is identical to the one above: the Action or stack gets a capability token instead of a broad deploy key — reaching the clear tree, excluded from every policy-protected path, writing only under its own agent/<name>/** namespace, and expiring on a clock you set.

Reference bridges are built, not yet published

The GitHub Action, the setup action, and the Spacelift hook live in the @tovio/ci-bridge package (DX-017, TOVIO's CI/CD compatibility track). The wrapper allowlists five operations — checkout, sync, git-bridge, health, status — takes secrets only as paths to mounted files, and never force-pushes across a bridge. The scoping principles here are stable; Marketplace listing and clean-runner publication evidence are the open items before the turnkey integrations are announced.

Every build is audited

Because a runner acts under a capability token, its activity lands in the same audit log as everything else:

  • Which token read which paths, and when.
  • Out-of-scope or no-clearance attempts, surfaced as security events you can route to alerting.

So "what did CI touch last night?" is a query, not a guess. The security guides cover reading and verifying the audit log.

Where to go next

  • AI agents & automation — the full capability-token model that CI runners share with coding agents.
  • Run a Git bridge — keep pipelines working while part of the team is still on Git.
  • On-premise — stand up the Forge that emits build events and required checks.
  • Security — policies, clearance, and the audit log your runners operate under.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure