docs(auth): document glab in the Claude Code sandbox

Kai Armstrongrequested to merge
docs/claude-code-sandbox-auth into main

Description

Documents how to run glab inside the Claude Code sandbox.

By default that sandbox allows writes only to the current working directory. Because glab stores credentials elsewhere, it cannot persist refreshed OAuth credentials. The command that triggers the refresh reports the write failure, but GitLab has already invalidated the previous single-use refresh token, so every later command fails with invalid_grant. The failure and the symptom are different commands, which is why it reads as credentials expiring on their own, and why users end up running glab auth login daily.

Adds a ## Claude Code sandboxing section covering two configurations, each with the risk it carries:

  1. Run glab outside the sandbox (excludedCommands). Keeps OAuth and short-lived tokens. Risk: glab is unconfined, and since it clones repositories and reaches hosts you give it, a prompt-injected agent could use it to write outside the working directory or send data out.
  2. Grant write access to credential storage (allowWrite). Keeps glab sandboxed. Risk: keychain write extends to the whole login keychain and to every sandboxed command, and cannot be narrowed.

Also adds a troubleshooting entry for invalid_grant so the error text leads back to this section.

The configuration directory is written as a <CONFIG_DIR> placeholder rather than a literal path. It resolves differently per user, and the reporter's own directory was ~/Library/Application Support/glab-cli, so a hardcoded ~/.config/glab-cli would have sent them to a directory glab never writes to.

Related Issues

Documentation half of #8262 (closed). The reporter confirmed option 1 is what they would choose, and that these findings matched their own diagnosis.

How has this been tested?

markdownlint-cli2 and vale --minAlertLevel error are clean, and the pre-push suite passed including lychee link checking.

Verified separately:

  • Both JSON examples parse as valid JSON, so copy-pasting them into settings.json cannot corrupt it. This is why the placeholder is used instead of a JSON comment, which Claude Code settings do not support.
  • make gen-docs leaves authentication.md untouched, so this hand-authored page is not at risk of being regenerated away.
  • The #claude-code-sandboxing anchor referenced from the troubleshooting entry resolves to the new heading.

This MR is intentionally standalone and does not depend on !3728 (merged), !3729 (merged), or !3730 (merged).

Merge request reports