Networking (Tailscale)

Automatically join WarpBuild runners to your Tailscale tailnet using OIDC authentication. Access private services, databases, and APIs from your CI jobs.

The Networking addon lets you automatically connect WarpBuild runners to your Tailscale tailnet when a CI job starts. This enables your workflows to securely access private services, databases, and internal APIs without exposing them to the public internet.

How It Works

You create a Network Addon Configuration in WarpBuild with your Tailscale OIDC Client ID.

In your GitHub Actions workflow, you add network.name=<config-name> to the runs-on label.

When the CI job starts, WarpBuild authenticates the runner to your tailnet using Tailscale OIDC and ephemeral node keys.

The runner joins your tailnet and can reach any device or service on it.

When the job finishes, the ephemeral node is automatically removed from your tailnet.

Prerequisites

A Tailscale account with admin access to your tailnet.

Setup

Create a Trust Credential in Tailscale

Open the Trust credentials page in the Tailscale admin console and click Add credentials. On the Settings step, configure:

Credential type: OIDC
Issuer: Custom issuer — https://api.warpbuild.com
Subject: warp-* — WarpBuild issues tokens with sub set to the runner instance ID (which is prefixed with warp-), so the wildcard matches all runners.

On the Scopes step, select Custom scopes and enable the minimum permissions:

Section	Scope	Access	Why
Keys > Auth Keys	`auth_keys`	Read + Write	Allows ephemeral auth key creation for node registration.

Under Tags, add the tags your runners will use (e.g., tag:ci). Tags passed via --advertise-tags in WarpBuild must be a subset of the tags configured here.

[!NOTE] All other scopes (Posture Attributes, Routes, Device Invites, etc.) can be left unchecked.

Copy the Client ID that Tailscale generates for this credential.

Create a Network Addon Configuration

In the WarpBuild dashboard, go to Addons > Networking in the sidebar. Click Create Addon and fill in:

Name: A descriptive name (e.g., production-tailnet). This is the name you'll use in your workflow labels.
Provider: Select Tailscale.
OIDC Client ID: The Client ID from Step 1.
Additional Arguments (optional): Extra flags to pass to the tailscale up command (e.g., --advertise-tags=tag:ci --accept-routes). See the Tailscale CLI reference for available flags.

[!NOTE] The --hostname, --auth-key, --client-id, --id-token, and --state flags are managed by WarpBuild and cannot be overridden in the additional arguments.

Use in Your Workflow

Add network.name=<config-name> to the runs-on label in your workflow file, where <config-name> matches the name of the addon configuration you created:

jobs:
  deploy:
    runs-on: warp-ubuntu-latest-x64-4x;network.name=production-tailnet
    steps:
      - uses: actions/checkout@v4

      - name: Access internal API
        run: |
          curl https://internal-api.myorg.tailnet.ts.net/health

      - name: Run database migrations
        run: |
          psql "postgres://db.myorg.tailnet.ts.net:5432/mydb" -f migrations.sql

Combining with Snapshots

You can combine the networking addon with snapshot runners in a single label:

jobs:
  build:
    # Network addon + snapshot restore
    runs-on: warp-ubuntu-latest-x64-4x;network.name=production-tailnet;snapshot.key=my-key

  test:
    # Network addon + snapshot create
    runs-on: warp-ubuntu-latest-x64-4x;network.name=production-tailnet;snapshot.enabled=true

Supported Platforms

Platform	Status
Linux (Ubuntu x64)	✅
Linux (Ubuntu arm64)	✅
macOS (arm64)	✅
Windows (x64)	✅

Tailscale is pre-installed on all WarpBuild runner images. The addon setup script starts the Tailscale daemon and authenticates on demand — it does not run when the networking addon is not requested.

For BYOC runners using custom images, ensure jq is installed. The addon setup script will automatically install Tailscale if not present. See Custom VM Images for prerequisites.

Additional Arguments

The Additional Arguments field accepts any flags supported by tailscale up. Common examples:

Flag	Description
`--advertise-tags=tag:ci`	Apply ACL tags to the runner node
`--accept-routes`	Accept subnet routes advertised by other nodes
`--accept-dns=false`	Disable Tailscale DNS overrides
`--advertise-routes=10.0.0.0/24`	Advertise routes from the runner

Multiple flags can be combined in a single string:

--advertise-tags=tag:ci --accept-routes --accept-dns=false

[!WARN] --hostname, --auth-key, --client-id, --id-token, and --state are reserved flags that are automatically set by WarpBuild and will be rejected if included in additional arguments.

ACL Tags

If you specify tags via additional arguments (e.g., --advertise-tags=tag:ci), make sure they are defined in your Tailscale ACL policy. Tags control what the runner node can access on your tailnet. For example:

{
  "tagOwners": {
    "tag:ci": ["autogroup:admin"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["tag:ci"],
      "dst": ["tag:internal-api:443"]
    }
  ]
}

Security

Runner nodes join as ephemeral nodes and are automatically removed from your tailnet when the CI job completes.
Authentication uses short-lived OIDC tokens signed by WarpBuild — no long-lived auth keys are stored.
You control access through Tailscale ACL tags and policies.