Fix the review findings in connect-tailscale

tailscaled is waited for before tailscale up, a tailscaled that already runs on
the runner is not taken over and down leaves a daemon it did not start, sudo is
used only when the job is not root, an exact version is required to install
(with an optional sha256 of the archive), and the guide states when the node is
ephemeral and calls @main until the release.

Refs #185
Task: MIL-012#4

guides/vpn-tailscale.md

@@ -5,8 +5,8 @@ a Gitea Actions runner, so the next steps of the same job (a deployment over
 SSH, a migration) can reach hosts on the tailnet. It does what the GitHub
 marketplace action `tailscale/github-action` does, written for Gitea Actions:
 that action is built for GitHub and has not been verified on Gitea. It is
-**experimental**: it lives on the branch `wireguard-vpn-action` until a trial
-shows it is wanted. For a plain tunnel without a third-party service, see
+**experimental**: it is on `main` but not released, and it has not yet run on a
+runner with a real tailnet (MIL-012). For a plain tunnel without a third-party service, see
 [WireGuard](vpn-wireguard.md).
 
 A node belongs to one job: every job that deploys joins on its own and logs out
@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v4.2.2
 
       - name: Connect Tailscale
-        uses: TirSystem/github-action/actions/connect-tailscale@v2
+        uses: TirSystem/github-action/actions/connect-tailscale@main
         with:
           oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
           tags: tag:ci
@@ -35,16 +35,17 @@ jobs:
 
       - name: Disconnect Tailscale
         if: always()
-        uses: TirSystem/github-action/actions/connect-tailscale@v2
+        uses: TirSystem/github-action/actions/connect-tailscale@main
         with:
           action: down
 ```
 
 If the short form does not resolve on your instance (Gitea looks for the action
 on the host set in `DEFAULT_ACTIONS_URL`), use the full address:
-`https://git.tirsystem.com/TirSystem/github-action/actions/connect-tailscale@v2`.
-To try the branch before it is released, replace `@v2` with
-`@wireguard-vpn-action`.
+`https://git.tirsystem.com/TirSystem/github-action/actions/connect-tailscale@main`.
+
+Until release 2.2.0 the actions exist only on `main`, so the examples call
+`@main`; `@v2` does not contain them yet. After the release, use `@v2`.
 
 ## Inputs
 
@@ -55,7 +56,8 @@ To try the branch before it is released, replace `@v2` with
 | `oauth-secret` | | The secret of an OAuth client with the scope `auth_keys`, as a secret. Needs `tags` |
 | `tags` | | ACL tags of the node, `tag:ci` or `tag:ci,tag:deploy`. Required with `oauth-secret` |
 | `hostname` | runner name | Name of the node in the tailnet |
-| `version` | `latest` | The version to install when the runner has no `tailscale`. Pin it |
+| `version` | | The exact version to install when the runner has no `tailscale`, for example `1.80.2`. Empty uses the installed one and fails when there is none |
+| `sha256` | | The SHA-256 of the downloaded archive `tailscale_<version>_<arch>.tgz`; the install fails when it differs. Recommended |
 | `userspace-networking` | `false` | `true` runs without a TUN device |
 | `args` | | Extra flags for `tailscale up`, for example `--accept-routes`. Never a secret |
 | `timeout` | `60` | Seconds to wait for the node |
@@ -74,15 +76,23 @@ To try the branch before it is released, replace `@v2` with
    start with `GITEA_` or `GITHUB_`.
 4. Rotate the secret when a person with access leaves.
 
-The node is ephemeral and its state is kept in memory, so it disappears from the
-tailnet when the job ends, even if the last step does not run.
+The state of the node is kept in memory. With an OAuth client the key is
+ephemeral, so the node disappears from the tailnet when the job ends, even if
+the last step does not run. With an auth key that is not ephemeral, a cancelled
+job can leave the node in the tailnet until `down` runs or it is removed in the
+admin console: create the key as ephemeral.
 
 ## The runner
 
-- The job runs as root or can use `sudo`. The action downloads the Tailscale
-  binaries from `pkgs.tailscale.com` when `tailscale` is not on the runner.
-  Pin `version`; a runner image that already contains Tailscale skips the
-  download.
+- The job runs as root, or `sudo` is available (the action uses `sudo` only
+  when the job is not root). The action downloads the Tailscale binaries from
+  `pkgs.tailscale.com` when `tailscale` is not on the runner; `version` is then
+  required, and `sha256` makes the install check the archive. A runner image
+  that already contains Tailscale skips the download.
+- The action starts its own `tailscaled`. It refuses to run when a `tailscaled`
+  already answers on the runner, because that daemon belongs to the host and
+  `down` would log it out: use the action on job containers, not on a runner
+  that runs jobs directly on a host with its own Tailscale.
 - **TUN mode** (the default) needs the capability `NET_ADMIN` and the device
   `/dev/net/tun` in the runner container: in the `act_runner` configuration set
   under `container:` `options: "--cap-add=NET_ADMIN --device=/dev/net/tun"`.
@@ -107,7 +117,9 @@ tailnet when the job ends, even if the last step does not run.
   never on a command line, and deletes the file at once;
 - prints errors as `::error::[category] message`, with the categories
   `configuration`, `environment` and `connection`;
-- on `down` logs the node out, stops `tailscaled` and deletes its work folder.
+- waits until `tailscaled` answers before `tailscale up` (up to 30 seconds);
+- on `down` logs the node out, stops `tailscaled` and deletes its work folder,
+  and only when this action started that daemon.
 
 The `file:` form of `--auth-key` needs a recent Tailscale; with an old pinned
 version `tailscale up` reports an invalid key.