Tailscale GitHub Action

This GitHub Action connects to your Tailscale network by adding a step to your workflow.

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

Subsequent steps in the Action can then access nodes in your Tailnet.

oauth-client-id and oauth-secret are an OAuth client for the tailnet to be accessed. We recommend storing these as GitHub Encrypted Secrets. OAuth clients used for this purpose must have the auth_keys scope.

tags is a comma-separated list of one or more ACL Tags for the node. At least one tag is required: an OAuth client is not associated with any of the Users on the tailnet, it has to Tag its nodes.

Nodes created by this Action are marked as Ephemeral to and log out immediately after finishing their CI run, at which point they are automatically removed by the coordination server. The nodes are also marked Preapproved on tailnets which use Device Approval

Prerequisites

Before using the Tailscale GitHub Action, ensure you have the following:

1. A Tailscale account with Owner, Admin, or Network admin permissions.
2. A GitHub repository that you have admin access to (required to set up the GitHub Action).
3. At least one configured [tag][kb-tags].
4. An [OAuth client][kb-oauth-clients] ID and secret OR an [auth key][kb-auth-keys].
5. A runner image version >= 2.237.1 (required to support running Node.js 24).

Eventual consistency

Propagating information about new peers - such as the node created by this action - across your tailnet is an eventually consistent process, and brief delays are expected. Until the GitHub workflow node becomes visible, other peers will not accept connections. It is best to verify connectivity to the intended nodes before executing steps that rely on them.

You can do this by adding a list of hosts to ping to the action configuration:

- name: Tailscale
  uses: tailscale/github-action@v4
  with:
    ping: 100.x.y.z,my-machine.my-tailnet.ts.net

or with the tailscale ping command if you do not know the peers at the time of installing Tailscale in the workflow:

tailscale ping my-target.my-tailnet.ts.net

The ping option will wait up to to 3 minutes for a connection (direct or relayed).

Tailnet Lock

If you are using this Action in a Tailnet Lock enabled network, you need to:

• Authenticate using an ephemeral reusable pre-signed auth key rather than an OAuth client.
• Specify a state directory for the client to store the Tailnet Key Authority data in.

- name: Tailscale
  uses: tailscale/github-action@v4
  with:
    authkey: tskey-auth-...
    statedir: /tmp/tailscale-state/

Defining Tailscale version

Which Tailscale version to use can be set like this:

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

If you'd like to specify the latest version, simply set the version as latest

- name: Tailscale
  uses: tailscale/github-action@v4
  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 https://pkgs.tailscale.com/stable/#static.

You can also specify version: unstable to use the latest unstable version of Tailscale. For Linux and Windows, this uses the version published at https://pkgs.tailscale.com/unstable, and for MacOS it uses the HEAD of the main branch of https://github.com/tailscale/tailscale/.

Cache Tailscale binaries

Caching can reduce download times and download failures on runners with slower network connectivity. As of v4 of this action, caching is enabled by default.

Although caching is generally recommended, you can disable it by passing 'false' to the use-cache input:

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