{"slug":"tailscale-with-gitlab-cicd","title":"Tailscale with GitLab CI/CD","tags":["tailscale"],"agent_summary":"Last validated: Dec 4, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Tailscale with GitLab CI/CD\r\n\r\nLast validated: Dec 4, 2025\r\n\r\nThe [Tailscale GitLab configuration](https://gitlab.com/tailscale-dev/gitlab-ci-cd) enables connecting your Tailscale network\r\n(known as a tailnet) to a [GitLab Runner](https://docs.gitlab.com/runner).\r\n\r\nWith this configuration, you can access nodes in your tailnet directly from your GitLab Runner. Some example uses are:\r\n\r\n- Securely deploy your application to an internal server\r\n- Securely reach your private test runners for specific platforms\r\n- Reach your database of test data without leaving it exposed on the internet\r\n- Access an internal deployment monitoring tool\r\n\r\n## [How it works](https://tailscale.com/docs/integrations/gitlab/gitlab-runner\\#how-it-works)\r\n\r\nWhen you add the Tailscale GitLab configuration to your runner, subsequent steps in your runner\r\ncan then access nodes in your tailnet. For example, the runner could access a node that has a\r\ndatabase of test data.\r\n\r\nThe Tailscale GitLab configuration requires an [auth key](https://tailscale.com/docs/features/access-control/auth-keys), which is tagged, reusable, ephemeral, and (if applicable) pre-approved. You store the auth key as an\r\n[external GitLab secret](https://docs.gitlab.com/ee/ci/secrets). The tag grants the access permission\r\nto any node created by your runner.\r\n\r\nWhen your runner executes, it uses the auth key to create an\r\n[ephemeral node](https://tailscale.com/docs/features/ephemeral-nodes). The node can then access nodes in your tailnet, subject to the\r\naccess applied to the tags.\r\n\r\nBecause the node is ephemeral, shortly after the action completes, the node is automatically removed\r\nfrom your tailnet. The next time the action runs, it creates a new ephemeral node, available only\r\nfor the new runner.\r\n\r\nAny node that the Tailscale GitLab configuration creates is [pre-approved](https://tailscale.com/docs/features/access-control/auth-keys#types-of-auth-keys) on\r\ntailnets that use [device approval](https://tailscale.com/docs/features/access-control/device-management/device-approval).\r\n\r\n## [Add Tailscale to a GitLab Runner](https://tailscale.com/docs/integrations/gitlab/gitlab-runner\\#add-tailscale-to-a-gitlab-runner)\r\n\r\n1. Create at least one [tag](https://tailscale.com/docs/features/tags) for the nodes that the GitLab configuration will create.\r\nFor example, `tag:ci`, which is used for this example. The access permissions that you grant to\r\nthe tags are applied to the nodes that will be created by the runner.\r\n\r\n2. Create an [auth key](https://tailscale.com/docs/features/access-control/auth-keys). We recommend that the [key type](https://tailscale.com/docs/features/access-control/auth-keys#types-of-auth-keys) is tagged,\r\nreusable, and ephemeral. If the tailnet uses [device approval](https://tailscale.com/docs/features/access-control/device-management/device-approval), ensure that the\r\nkey type is also pre-approved.\r\n\r\n3. Create a [GitLab secret](https://docs.gitlab.com/ee/ci/secrets) with the name `TAILSCALE_AUTHKEY` and the value set to your auth key.\r\nThen use the `authkey` field to reference the secret in your runner. For example:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ntailscale up --auth-key=${TAILSCALE_AUTHKEY} --hostname=\"gitlab-$(cat /etc/hostname)\" --accept-routes\r\n```\r\n\r\n\r\nWhen the action runs, it creates an ephemeral node. The node can access nodes in your tailnet,\r\nsubject to the access rules applied to the specified tag or tags. In the rest of your runner,\r\naccess other nodes in your tailnet as needed.\r\n\r\nThe ephemeral node is automatically cleaned up shortly after the action finishes.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Tailscale with GitLab CI/CD

\n

Last validated: Dec 4, 2025

\n

The Tailscale GitLab configuration enables connecting your Tailscale network\r\n(known as a tailnet) to a GitLab Runner.

\n

With this configuration, you can access nodes in your tailnet directly from your GitLab Runner. Some example uses are:

\n\n

How it works

\n

When you add the Tailscale GitLab configuration to your runner, subsequent steps in your runner\r\ncan then access nodes in your tailnet. For example, the runner could access a node that has a\r\ndatabase of test data.

\n

The Tailscale GitLab configuration requires an auth key, which is tagged, reusable, ephemeral, and (if applicable) pre-approved. You store the auth key as an\r\nexternal GitLab secret. The tag grants the access permission\r\nto any node created by your runner.

\n

When your runner executes, it uses the auth key to create an\r\nephemeral node. The node can then access nodes in your tailnet, subject to the\r\naccess applied to the tags.

\n

Because the node is ephemeral, shortly after the action completes, the node is automatically removed\r\nfrom your tailnet. The next time the action runs, it creates a new ephemeral node, available only\r\nfor the new runner.

\n

Any node that the Tailscale GitLab configuration creates is pre-approved on\r\ntailnets that use device approval.

\n

Add Tailscale to a GitLab Runner

\n
    \n
  1. \n

    Create at least one tag for the nodes that the GitLab configuration will create.\r\nFor example, tag:ci, which is used for this example. The access permissions that you grant to\r\nthe tags are applied to the nodes that will be created by the runner.

    \n
    2. \n
  2. \n

    Create an auth key. We recommend that the key type is tagged,\r\nreusable, and ephemeral. If the tailnet uses device approval, ensure that the\r\nkey type is also pre-approved.

    \n
    3. \n
  3. \n

    Create a GitLab secret with the name TAILSCALE_AUTHKEY and the value set to your auth key.\r\nThen use the authkey field to reference the secret in your runner. For example:

    \n
    4. \n
\n
tailscale up --auth-key=${TAILSCALE_AUTHKEY} --hostname=\"gitlab-$(cat /etc/hostname)\" --accept-routes\n
\n

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

\n

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

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}