docs: explain OAuth client use with the tailscale client and GitHub Action

The upstream client only runs the OAuth exchange for tskey-client- secrets and
reads the control URL from a baseURL attribute, not --login-server. Document the
prefix swap, baseURL, and authkey-not-oauth-secret for the GitHub Action.

Author: kradalby

docs/ref/api.md

@@ -58,6 +58,39 @@ Headscale server at `/api/v1/docs` for details.
         https://headscale.example.com/api/v1/auth/register
     ```
 
+## OAuth clients and the Tailscale GitHub Action
+
+Headscale also serves a subset of the Tailscale-compatible API at `/api/v2`, which
+accepts **OAuth 2.0 client-credentials** in addition to API keys. This lets parts
+of the Tailscale ecosystem drive Headscale, including the official
+[`tailscale/github-action`](https://github.com/tailscale/github-action).
+
+Create an OAuth client and note its secret (shown once):
+
+```shell
+headscale oauth-clients create --scope auth_keys --tag tag:ci
+```
+
+The official action can use the secret as an auth key, but the upstream Tailscale
+client has two requirements when targeting a self-hosted control server:
+
+- The secret must be prefixed `tskey-client-`. Headscale issues `hskey-client-…`
+  but accepts the `tskey-client-` alias, so swap the prefix.
+- The OAuth exchange URL is read from a `baseURL` attribute on the secret itself
+  (not from `--login-server`). Append your Headscale URL.
+
+```yaml
+- uses: tailscale/github-action@v4
+  with:
+    # hskey-client-... with the prefix swapped to tskey-client- and baseURL appended
+    authkey: tskey-client-<id>-<secret>?baseURL=https://headscale.example.com&ephemeral=true&preauthorized=true
+    args: --login-server=https://headscale.example.com --advertise-tags=tag:ci
+```
+
+Use the action's `authkey` input, not `oauth-secret`: the latter appends its own
+query parameters and would mangle `baseURL`. The client must advertise the tag(s)
+the OAuth client owns.
+
 ## Remote control
 
 The `headscale` binary can control a Headscale instance from a remote machine over the HTTP API.

hscontrol/api/v2/README.md

@@ -75,6 +75,38 @@ operator is OAuth-only. Supporting OAuth lets all of them drive Headscale.
   **Argon2id** hash of the secret (no JWT, no signing keys). `OAuthClient` and
   `OAuthAccessToken` live in `types/oauth.go` and `db/oauth.go`.
 
+## OAuth with the tailscale client and GitHub Action
+
+The upstream `tailscale` client (and the official
+[`tailscale/github-action`](https://github.com/tailscale/github-action)) can use
+an OAuth client secret directly as an auth key: it runs the client-credentials
+exchange itself (`feature/oauthkey`), mints an auth key, and registers. Two
+Tailscale-specific quirks apply when pointing it at Headscale:
+
+- It only attempts the exchange when the secret is prefixed **`tskey-client-`**.
+  Headscale issues `hskey-client-…` but `AuthenticateOAuthClient` accepts the
+  `tskey-client-` alias too, so swap the prefix: `tskey-${SECRET#hskey-}`.
+- It exchanges against a **`baseURL`** read from the secret's query string
+  (default `https://api.tailscale.com`); `--login-server` only sets the
+  registration server, not the exchange. Append your Headscale URL.
+- The exchange requires `--advertise-tags`; registration accepts advertised tags
+  that are a subset of the key's own tags.
+
+So a working auth key is
+`tskey-client-<id>-<secret>?baseURL=https://headscale.example.com&ephemeral=true&preauthorized=true`.
+In the GitHub Action, pass it as the `authkey` input (the `oauth-secret` input is
+unusable here: it appends its own query parameters, which collide with `baseURL`):
+
+```yaml
+- uses: tailscale/github-action@v4
+  with:
+    authkey: tskey-client-<id>-<secret>?baseURL=https://headscale.example.com&ephemeral=true&preauthorized=true
+    args: --login-server=https://headscale.example.com --advertise-tags=tag:ci
+```
+
+The OAuth client needs the `auth_keys` scope and the tag(s) it assigns. The
+end-to-end flow is exercised in `.github/workflows/test-v2-api.yaml`.
+
 ## Adding an endpoint
 
 Worked example: the keys resource (`keys.go`) = Tailscale auth keys = Headscale