CI & agent credentials

CI jobs and coding agents often need a Cloud tunnel of their own — a preview app, a smoke-test target, a sandbox the agent can reach. Instead of storing a long-lived token, a team can let a repository mint short-lived tunnel credentials on demand, scoped to the team’s subdomain. You grant this per repository with a trust rule; nothing works until a rule exists.

Everything here lives on app.portzero.net → Teams → your team → CI & agent credentials. It is owner/admin only, and needs a team plan.

Tunnel names in a team

A team owns the subdomain --<team-slug>. Every tunnel a member (or a CI job, or an agent) registers sits under it:

<label>--<team-slug>.tunnel.portzero.cloud

You choose the <label>; Port Zero appends --<team-slug> for you. If the team has Require every member’s cloud tunnel to sit under the team subdomain turned on, then PZ_TUNNEL must be <label>--<team-slug> — a bare label is rejected. Labels cannot contain -- (that separator marks the team boundary). See Tunnels & PZ_TUNNEL for the naming rules.

Trust rules

A trust rule says “this repository may mint tunnels named like this.” Add one under CI & agent credentials → Trust rules:

Field	Example	Meaning
Repository	`acme/app`	The `owner/repo` allowed to mint credentials.
Template	`ci-{run-id}`	The tunnel label it may claim. `--<team-slug>` is appended automatically, so templates cannot contain `--`.
Ref (optional)	`refs/heads/main`	Restrict to one branch/tag. Blank means any ref.
Description (optional)	`CI previews`	A note for your teammates.

{run-id} is filled in for you — the GitHub Actions run id, or a nonce-derived id for repo-proof auth (below) — so each run gets its own distinct tunnel name.

GitHub Actions (OIDC)

With a trust rule in place, a workflow exchanges its GitHub OIDC token for a team-scoped tunnel credential. No secret is stored — the trust rule is the authorization. Grant the job id-token: write and pass the team to the tunnel action’s oidc-team input:

permissions:
  id-token: write        # required for the OIDC exchange
  contents: read
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: portzeronetwork/tunnel-action@v1
        with:
          oidc-team: acme          # your team slug
          tunnel: ci-${{ github.run_id }}   # matches the `ci-{run-id}` template
      # the tunnel is now up at ci-<run-id>--acme.tunnel.portzero.cloud

The exchange only succeeds when the repository, template, and ref match a trust rule; a mismatch fails with a message naming what to fix. See the tunnel-action README for the full input list and container-job notes.

Coding agents & scripts (repo-proof)

Anything with git push access to the repository — an agent sandbox, a local script — can authenticate by proving it holds the repo, no OIDC needed:

portzero login --github-repo --team acme

Repo-proof auth needs the Port Zero GitHub App installed on the repository and linked to the team. Install it once from CI & agent credentials → Install the Port Zero GitHub App; GitHub redirects you back to finish linking the installation to this team. Once linked, repo-proof login works for every repository the installation covers, subject to the same trust rules.

To set an agent up end to end (the sandbox hook, instructions, and MCP server), run portzero agents setup and see AI agents.

Checklist

Team plan active, and (optionally) the team subdomain requirement decided.
A trust rule for the repository, with a template you’ll use as the tunnel label.
For GitHub Actions: id-token: write + the tunnel action’s oidc-team input.
For agents/scripts: the Port Zero GitHub App installed and linked, then portzero login --github-repo --team <slug>.

The Repositories using CI credentials list on the same page shows which repos have exchanged credentials and when — a quick way to confirm a rule is live.