Text of tailscale.com › docs › integrations › github › gitops as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GitOps for Tailscale with GitHub Actions · Tailscale Docs

Visit us at ReInvent How to find us → Documentation GitOps for Tailscale with GitHub Actions Last validated: Dec 5, 2025 | | View as Markdown Access control policies define what users or devices are permitted to access in your Tailscale network (known as a tailnet). An alternative to managing the access control policy changes in the Access controls page of the admin console is to use GitOps to manage the access control policy changes.

This topic provides details on how to use GitHub Actions to automatically apply and test access control policy changes to your tailnet. GitOps for Tailscale is available for all plans . Prerequisites In addition to already having your own Tailscale network, you need: A GitHub account. Working knowledge of GitHub, including committing changes, creating and merging pull requests. A private GitHub repository that will contain your tailnet policy file.

Make sure this repository is private, as tailnet policy files contain personally identifiable information (PII), such as your users' email addresses. A Tailscale federated identity , OAuth client , or API access token for your tailnet. You can create a federated identity or an OAuth client in the Trust credentials page of the admin console, or you can create an API access token in the Keys page of the admin console. If you use a trust credential, the credential needs the policy_file:read scope to be able to read and validate the tailnet policy file, or the policy_file scope to be able to read, validate, and modify the tailnet policy file.

For information about other scopes that are required when using the policy_file:read or the policy_file scopes, refer to the trust credentials scopes documentation. GitHub Action to sync Tailscale access control policies Tailscale publishes a GitHub Action to Sync Tailscale access control policies , available in the GitHub Actions Marketplace. You do not need to use this GitHub Action to set up a GitOps pattern — you can also write your own Action or use another CI/CD tool.

What this action does On pull requests that target the main branch, the Test ACL step (action test ) will send your tailnet policy file to Tailscale to determine whether the access control policy is valid and whether all tests pass. Tailscale will provide your workflow with the result of those checks. On push (merge) operations that target the main branch, the Deploy ACL step (action apply ) will again check access control policy validity and run tests, with Tailscale reporting back the results to your workflow.

If the tests succeed, the merge will complete and the workflow will automatically apply your access control policy changes to your tailnet. If the tests fail, an error will prevent the merge from continuing. You can refer to the status of the workflow in the GitHub user interface's Actions tab for your pull request. Look for a workflow with the name you used in .github/workflows/tailscale.yml , Tailscale ACL syncing .

Inputs The following inputs apply to the Sync Tailscale ACLs action. action (Required): One of test or apply . If test , the action will run ACL tests only—it won't update your ACLs in Tailscale. If apply , the action will run ACL tests and, if the ACL tests succeed, then update your ACLs in Tailscale. This enables you to use pull requests to make changes, with CI preventing you from pushing a bad change out to production. oauth-client-id / audience , or oauth-client-id / oauth-secret , or api-key (Required): A credential to allow the action to interact with your tailnet.

You may use an oauth-client-id and audience , or an oauth-client-id and oauth-secret , or an api-key . You can create a trust credential in the Trust credentials page of the admin console, or you can create an API access token in the Keys page of the admin console. policy-file (Optional): The path to your tailnet policy file in the repository. If not set this defaults to policy.hujson in the root of your repository. tailnet (Required): This is your organization, which you can find in the General settings page of the admin console.

Set up your GitOps configuration In your GitHub repository, 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 will need to add the policy-file argument to the with blocks in your GitHub Actions configuration discussed below. Otherwise, the GitHub action will default to policy.hujson as the tailnet policy file.

Commit the tailnet policy file and push it to GitHub. For example, if you are using the command line: git add . git commit -sm "policy: import from admin console" git push -u origin main Create the following GitHub Actions secrets in your repository's settings: You may either supply Tailscale OAuth client credentials or a Tailscale API key. If you supply both, the OAuth credentials will be used. TS_TAILNET : Use your tailnet ID as the value.

You can find your tailnet ID in the General page of the admin console. TS_OAUTH_ID : Use your Tailscale OAuth client ID as the value. TS_OAUTH_SECRET : Use your Tailscale OAuth client secret as the value. TS_API_KEY : Use your Tailscale API access token as the value. These secrets provide the configuration for the action. Make a new GitHub Actions workflow that uses the Sync Tailscale ACLs GitHub Action. Federated identity OAuth client API key Create a file named .github/workflows/tailscale.yml .

Paste in the following YAML: name : Sync Tailscale ACLs on : push : branches : [ "main" ] pull_request : branches : [ "main" ] jobs : acls : runs-on : ubuntu - latest steps : - uses : actions/checkout@v6 - name : Deploy ACL if : github.event_name == 'push' id : deploy - acl uses : tailscale/gitops - acl - action@v1 with : oauth-client-id : $ { { secrets.TS_OAUTH_ID } } audience : $ { { secrets.TS_AUDIENCE } } tailnet : $ { { secrets.TS_TAILNET } } action : apply - name : Test ACL if : github.event_name == 'pull_request' id : test - acl uses : tailscale/gitops - acl - action@v1 with : oauth-client-id : $ { { secrets.TS_OAUTH_ID } } audience : $ { { secrets.TS_AUDIENCE } } tailnet : $ { { secrets.TS_TAILNET } } action : test If you don't use the name main for your default branch, update the branches fields in the YAML.

This workflow appropriately uses the secrets.TS_OAUTH_ID , secrets.TS_AUDIENCE , and secrets.TS_TAILNET environment variables to access your secrets. Do not place your actual secret values in .github/workflows/tailscale.yml —use the environment values as depicted in the example. Commit and push .github/workflows/tailscale.yml . The main steps in the action are installing gitops-pusher , setting the correct environment variables and flags, and then running the workflow.

For more information, refer to GitHub Action configuration . With this setup, you have created a continuous integration (CI) that automatically tests and pushes your tailnet policy file changes to Tailscale! Follow the instructions to prevent others from accidentally modifying your tailnet policy file in the admin console. Push changes to your tailnet policy file Now that your configuration has been set up, any time you want to update your ACL, modify the tailnet policy file in your repository and use the typical GitHub authoring/review/merge flow.

You can check the status of the ACL validity checks and ACL tests in the GitHub UI in the Actions tab for your pull request. Look for a workflow with the name you used in .github/workflows/tailscale.yml , Sync Tailscale ACLs . Prevent others from accidentally modifying your tailnet policy file On June 3, 2025, we announced the deprecation of the GitOps code comment technique for locking the policy file editor in the admin console.

Tailnets that were using this method were automatically migrated to use the setting in the admin console. The code comment is no longer effective for locking the policy file editor. To prevent other

The rest of this page is on the live site.