nix-github-rate-limit

name	nix-github-rate-limit
description	Prevents and handles GitHub API rate limits during Nix commands. Use when running nix flake, nix run, nix build, nix shell, or comma against GitHub-backed inputs.

Nix GitHub Rate Limit

Use this skill before running Nix commands that may fetch GitHub-backed flakes or packages, especially nix flake update, nix run github:..., nix run nixpkgs#..., nix build, nix shell, and comma.

Default Approach

Prefer ephemeral token injection from GitHub CLI. Do not write GitHub tokens to nix.conf, repository files, skill files, shell config, or command arguments.

Use command substitution inside NIX_CONFIG for a single command when gh is already authenticated. Shell history records the literal command substitution, not the expanded token:

env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix flake update

If ghtkn is configured and a short-lived GitHub App user token is preferred:

env NIX_CONFIG="access-tokens = github.com=$(ghtkn get)" nix flake update

If GITHUB_TOKEN is already present in the environment, bridge it into Nix's documented access-tokens setting without exposing the token value in the command text:

env NIX_CONFIG="access-tokens = github.com=$GITHUB_TOKEN" nix flake update

Do not create GITHUB_TOKEN by pasting a raw token into the terminal or an agent tool call.

For this dotfiles repo:

env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix run .#build
env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix run .#switch
env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix run .#update

For missing tool execution:

env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix run nixpkgs#<package> -- <args>
env NIX_CONFIG="access-tokens = github.com=$(gh auth token)" nix shell nixpkgs#<package> --command <command>

Workflow

1. If the command is a Nix command that may touch GitHub, check whether gh is available and authenticated:

   command -q gh; and gh auth status
   

2. If GITHUB_TOKEN is already set, run the Nix command with NIX_CONFIG="access-tokens = github.com=$GITHUB_TOKEN".

3. If gh is authenticated, run the Nix command with NIX_CONFIG="access-tokens = github.com=$(gh auth token)".

4. If ghtkn is configured and the user prefers short-lived GitHub App tokens, use NIX_CONFIG="access-tokens = github.com=$(ghtkn get)".

5. If no safe token source is available, run the command normally unless the user explicitly wants to authenticate first.

6. If a GitHub API rate limit error appears, retry once with the safest available NIX_CONFIG wrapper.

History Safety

• Follow the global command privacy rule: command text, shell history, process lists, terminal output, tool invocation logs, and coding-agent transcripts must not contain raw tokens.
• Prefer inline command substitution such as $(gh auth token) or $(ghtkn get) inside the command the user runs.
• It is also acceptable to reference an existing environment variable by name, such as $GITHUB_TOKEN; do not assign the raw value in the command.
• Do not paste a raw token into the terminal, even temporarily.
• Do not run commands like env NIX_CONFIG="access-tokens = github.com=ghp_..." ....
• Do not place raw tokens in agent tool calls, command logs, or explanatory messages.
• Do not store a token in fish universal variables, exported shell variables, direnv files, or shell history cleanup scripts.
• If a raw token was accidentally pasted, tell the user to rotate or revoke it. Deleting shell history is not enough.

Avoid

• Do not use --access-tokens "github.com=$(gh auth token)" because command arguments can be exposed via process listings.
• Do not store PATs in ~/.config/nix/nix.conf, /etc/nix/nix.conf, repository files, or dotfiles by default.
• Do not suggest broad PAT scopes. Public GitHub fetches should not need additional repository permissions.
• Do not print tokens, echo tokens, or include them in logs, summaries, commits, PR descriptions, or issue comments.

Notes

• Unauthenticated GitHub REST API requests are rate limited much more aggressively than authenticated requests.
• NIX_CONFIG keeps the token out of the command arguments, but environment variables can still be visible to sufficiently privileged local processes. Prefer it only for short-lived commands.
• If GITHUB_TOKEN is already provided by CI or a controlled environment, Nix may use it, but do not create or persist it just for local interactive use.