Connect GitHub Actions Runners

This guide shows you how to connect GitHub Actions runners to Riptides using the GitHubActions verifier. Runners authenticate automatically using the signed OIDC token provided by GitHub Actions, with no join tokens or long-lived credentials required.

Prerequisites

A running Riptides control plane (see Getting Started)
kubectl configured to access the Riptides API
A GitHub repository or organisation whose workflows you want to connect

How It Works

GitHub Actions provides every runner with an OIDC token issued by https://token.actions.githubusercontent.com. The Riptides daemon requests this token from the Actions token endpoint using the ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables that GitHub injects automatically. The control plane verifies the token signature against GitHub’s public JWKS and checks that the repository_owner claim matches the Verifier’s repositoryOwner field.

No managed identity, no cloud account, no secrets. The runner’s GitHub identity is the credential.

Step 1: Create a GitHubActions Verifier

Create a Verifier that accepts runners from your GitHub organisation. repositoryOwner is required and restricts authentication to your org only.

apiVersion: auth.riptides.io/v1alpha1
kind: Verifier
metadata:
  name: github-actions
  namespace: riptides-system
spec:
  GitHubActions:
    repositoryOwner: your-org
    audience: riptides

Apply it:

riptides-cli ctl apply -f verifier-github-actions.yaml

Confirm the Verifier is available:

riptides-cli ctl get verifiers

Expected output:

NAME             STATE
github-actions   Available

Narrowing to a Specific Repository or Branch

You can restrict the Verifier further using optional fields:

spec:
  GitHubActions:
    repositoryOwner: your-org
    repository: your-org/deploy-service   # only this repository
    environment: production               # only the "production" GH environment
    ref: refs/heads/main                  # only the main branch
    audience: riptides

Each field that is set adds a corresponding claim check. A token that does not match all set fields is rejected.

Step 2: Add the Action to Your Workflow

Add the riptideslabs/setup-riptides action to your workflow. The job must have id-token: write permission so GitHub can issue an OIDC token.

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # required, allows GitHub to issue an OIDC token
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: riptideslabs/setup-riptides@v1
        with:
          controlplane-url: https://<your-env-id>.console.riptides.io

      # From here the runner has a verified SPIFFE identity and all outbound
      # connections are transparently mTLS-secured by the Riptides daemon.
      - name: Deploy
        run: ./deploy.sh

The action installs the kernel driver and daemon, runs riptides daemon auth --plugin GitHubActions to exchange the OIDC token for a SPIFFE x509 identity certificate, and starts the daemon as a systemd service.

To follow live logs during a run:

sudo journalctl -u riptides -f

Pinning the Audience

The audience input must match the audience field in your Verifier. The default for both is riptides.

      - uses: riptideslabs/setup-riptides@v1
        with:
          controlplane-url: https://<your-env-id>.console.riptides.io
          audience: my-custom-audience

spec:
  GitHubActions:
    repositoryOwner: your-org
    audience: my-custom-audience

Verify Runners Appear

After a workflow run, check that the runner daemon registered with the control plane:

riptides-cli ctl get daemons

You should see an entry like:

NAME                                   WORKLOAD-ID                                                    STATE
a1b2c3d4-e5f6-7890-abcd-e01234567890  riptides/daemon/your-org/your-org/deploy-service/CI            Connected

The daemon will disappear from this list once the job finishes and the runner is destroyed.

Step 3: Assign Workload Identities

Create a WorkloadIdentity to assign a SPIFFE identity to processes running on your GitHub Actions runners. Scope it to the daemon’s workload ID so it only applies to runners from your repo:

apiVersion: core.riptides.io/v1alpha1
kind: WorkloadIdentity
metadata:
  name: github-actions-deployer
  namespace: riptides-system
spec:
  workloadID: ci/github-actions/deployer
  scope:
    daemonGroup:
      id: riptides/daemongroup/github-actions-runners
  selectors:
    - process:name: deploy.sh
  connection:
    tls:
      mode: PERMISSIVE