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. 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 ACL tag. The ACL 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 ACL 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

1. Create at least one ACL 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.

2. 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.

3. Create a GitHub secret with the name TS_OAUTH_CLIENT_ID and assign your OAuth client ID as the secret value.

4. Create a GitHub secret with the name TS_OAUTH_SECRET and assign your OAuth client secret as the secret value.

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

   - name: Tailscale
     uses: tailscale/github-action@v2
     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 ACL 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 ACL 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.

Using an auth key

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@v2
  with:
    authkey: ${{ secrets.TAILSCALE_AUTHKEY }}