Tailscale GitHub Action

The Tailscale GitHub Action is a GitHub Action that enables connecting your Tailscale network (known as a tailnet) to a GitHub Actions workflow.

With the Tailscale GitHub Action, you can access nodes in your tailnet directly from your GitHub workflow. Some example uses are:

Securely deploy your application to an internal server.
Securely reach your private test runners for specific platforms.
Reach your database of test data without leaving it exposed on the internet.
Access an internal deployment monitoring tool.

The Tailscale GitHub Action is an available action in the GitHub Marketplace.

How it works

When you add the Tailscale GitHub Action to your workflow, subsequent steps in your GitHub Action can then access nodes in your tailnet. For example, the workflow could access a node that has a database of test data.

The Tailscale GitHub Action requires an OAuth client ID and secret OR an auth key, which is tagged, reusable, ephemeral, and (if applicable) pre-approved. We recommend that you use an OAuth client ID and secret. The OAuth client requires the auth_keys scope. You store the OAuth client ID and secret as GitHub encrypted secrets. OAuth clients are not associated with any user in your tailnet, so they require at least one tag. The tag grants the access permission to any node created by your workflow.

When your workflow runs, it uses the OAuth client ID and secret to create an ephemeral node. The node can then access nodes in your tailnet, subject to the access applied to the tags.

Because the node is ephemeral, shortly after the action completes, the node is automatically removed from your tailnet. The next time the action runs, it creates a new ephemeral node, available only for the new workflow.

Any node that the Tailscale GitHub Action creates is pre-approved on tailnets that use device approval.

Add the Tailscale GitHub Action to a workflow

Create at least one tag for the nodes that the Tailscale GitHub Action will create. For example, tag:ci, which is used for this example. The access permissions that you grant to the tags are applied to the nodes that will be created by the workflow.
Set up a Tailscale OAuth client. You'll need the value of your OAuth client ID and secret. If you are using an auth key instead of an OAuth client, see Using an auth key.
Create a GitHub secret with the name TS_OAUTH_CLIENT_ID and assign your OAuth client ID as the secret value.
Create a GitHub secret with the name TS_OAUTH_SECRET and assign your OAuth client secret as the secret value.

In your GitHub Actions workflow, connect to your tailnet by using the Tailscale GitHub Action. For example:

- name: Tailscale
  uses: tailscale/github-action@v3
  with:
    oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
    oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
    tags: tag:ci

oauth-client-id and oauth-secret are your OAuth client ID and secret, respectively. tags is a comma-separated list of the tags applied to the nodes that will be created by this action. These tags must already exist in your tailnet.

When the action runs, it creates an ephemeral node. The node can access nodes in your tailnet, subject to the access rules applied to the specified tag or tags. In the rest of your workflow, access other nodes in your tailnet as needed.

The ephemeral node is automatically cleaned up shortly after the action finishes.

Auth key considerations

If you are using an auth key instead of an OAuth client, we recommend that the key type is tagged, reusable, and ephemeral. If the tailnet uses device approval, ensure that the key type is also pre-approved.

To use the auth key for your workflow, create a GitHub secret with the name TAILSCALE_AUTHKEY and the value set to your auth key. Then use the authkey field to reference the secret in your workflow. For example:

- name: Tailscale
  uses: tailscale/github-action@v3
  with:
    authkey: ${{ secrets.TAILSCALE_AUTHKEY }}

Tailscale GitHub Action version

Tailscale does not update the client version for the Tailscale GitHub Action every time there is a new Tailscale client release. The default version specified in the base YAML file remains unchanged for long periods of time. It changes only when there is a meaningful reason to do so.

If you would like to set the version yourself, add a version entry to your workflow:

  - name: Tailscale
    uses: tailscale/github-action@v3
    with:
      oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
      oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
      tags: tag:ci
      version: 1.66.0

If you would like to specify the latest version, set the version to latest.

  - name: Tailscale
    uses: tailscale/github-action@v3
    with:
      oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
      oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
      tags: tag:ci
      version: latest

You can find the latest Tailscale stable version number at our stable release track.

Cache Tailscale binaries

Caching can reduce download times and download failures on runners with slower network connectivity. Although caching is not enabled by default, it is generally recommended.

You can opt in to caching Tailscale binaries by passing 'true' to the use-cache input:

  - name: Tailscale
    uses: tailscale/github-action@v3
    with:
      oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
      oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
      use-cache: 'true'