GitOps for Tailscale ACLs with Bitbucket

Access Control Lists (ACLs) define what users or devices are permitted to access in your Tailscale network (known as a tailnet). An alternative to managing the ACL changes in the Access Controls page of the admin console is to use GitOps for Tailscale ACLs to manage the ACL changes. This article provides details on how to use Bitbucket Pipelines to automatically apply and test ACL changes to your tailnet.

GitOps for Tailscale ACLs is available for all plans.

Prerequisites

In addition to already having your own Tailscale network, you need:

A Bitbucket account.
Working knowledge of Bitbucket procedures including committing changes, creating pull requests, and merging pull requests.
A private Bitbucket repository that will contain your tailnet policy file.
Make sure this repo is private, as tailnet policy files contain personally identifiable information (PII), such as users email addresses.
A Tailscale API access token for your tailnet. You can create an API access token in the Keys page of the admin console.

Set up your GitOps configuration

In your Bitbucket repo, create a file named policy.hujson. Copy your tailnet policy file contents from the Access Controls page of the admin console into this file.

If you want to change the tailnet policy file name to something else, you need to modify the --policy-file argument used by the gitops-pusher binary in the Bitbucket pipeline discussed below.

To prevent others admins in your organization from accidentally changing your tailnet policy file, add a comment as the first line in the policy file so the Access Controls page can display a warning:
```
// This tailnet's ACLs are maintained in <url>
```
Ensure this comment is the first line of the policy file, otherwise the Access Controls page will not display the warning.
Commit the tailnet policy file and push it to Bitbucket. For example, if you are using the command line:
```
git add .
git commit -sm "policy: import from admin console"
git push -u origin main
```
Within your repository's Repository variables settings, create the following Bitbucket secured variables:
- TS_API_KEY: Use your Tailscale API access token as the value.
- TS_TAILNET: Use your organization as the value. For example, example.com or myemail@example.com. You can find your organization in the Settings page of the admin console.
These secrets provide the configuration for the pipeline.

Make a new Bitbucket Pipelines pipeline that uses the gitops-pusher binary.

Create a file named bitbucket-pipelines.yml in the Source folder and paste in the following:

image: golang

pipelines:
  default:
     - step:
         name: Test ACL
         script:
           - go install tailscale.com/cmd/gitops-pusher@latest
           - gitops-pusher --policy-file ./policy.hujson test
  branches:
    main:
      - step:
          name: Deploy ACL
          script:
            - go install tailscale.com/cmd/gitops-pusher@latest
            - gitops-pusher --policy-file ./policy.hujson apply

For information about Bitbucket Pipelines options and properties, see Bitbucket Pipelines configuration reference.

Commit and push bitbucket-pipelines.yml.

The main steps in the pipeline are installing and building the gitops-pusher binary and then running the binary. On pull requests, the Test ACL step will send your tailnet policy file to Tailscale to determine whether the ACL is valid and whether all ACL tests pass. Tailscale provides your pipeline with the result of those checks, which you can view in the Bitbucket Pipelines page.

On push (merge) operations that target the main branch, the Deploy ACL step will send your tailnet policy file to Tailscale to determine whether the tailnet policy file is valid and whether all ACL tests pass. If this portion succeeds, Tailscale then applies your tailnet policy file update to your tailnet. Tailscale provides your pipeline with the result of this step, which you can view in the Bitbucket Pipelines page.

With this setup, you have created a continuous integration (CI) that automatically tests and pushes your tailnet policy file changes to Tailscale!

Push changes to your Tailscale ACL

Now that your configuration has been set up, any time your want to update your ACL, modify the tailnet policy file in your repo and use the typical Bitbucket authoring/review/merge flow.

Prevent others from accidentally modifying your tailnet policy file

To prevent others admins in your organization from accidentally changing your tailnet policy file, add the following comment as the first line in the policy file with the URL of your repository so the Access Controls page can display a warning:

// This tailnet's ACLs are maintained in <url>

A screenshot of the warning shown in the tailnet policy file.

Any admin with permissions to edit the tailnet policy file will still be able to edit it directly by selecting Edit anyway, for example, in case of emergency.

A screenshot of the warning shown when trying to edit a tailnet policy file which is using GitOps.

Any changes made in the admin console will be overwritten the next time the Bitbucket pipeline is used.

Revert the most recent change to your ACL

If you need to revert the most recent change, use the Bitbucket Pull requests page to find and then revert the merged pull request.

Remove your GitOps configuration

Remove the following line from the top of tailnet policy file. You can make this edit through your current GitOps configuration, or by manually editing your tailnet policy file.
```
// This tailnet's ACLs are maintained in <url>
```
Revoke any associated Tailscale API access tokens for this configuration.
Archive or delete the associated BitBucket repository.

Additional information

Any manual tailnet policy file changes in the admin console won't be reflected in your Bitbucket version of the tailnet policy file. The next time you use the Bitbucket pipeline, any changes made in the Tailscale admin console will be overwritten.
Tailscale API access tokens expire and currently there is no mechanism to have them automatically renewed. To handle the expiration, create a new API access token and update the Bitbucket TS_API_KEY secret to use the new value. Tailscale API access tokens after 90 days (or less if the key has a shorter expiry) but updating the Bitbucket secret monthly is a good practice.

When you no longer need to use a Tailscale API access token, make sure you revoke it in the Keys page of the Tailscale admin console.
Tailscale tailnet policy files are in HuJSON, a JSON format with trailing commas and comments. If you don't want to write your tailnet policy files in HuJSON directly, you can use a tool that lets you generate JSON in the same schema as the HuJSON format.