From 4d134b021834ac90528f9bee1ee0d6716fe43005 Mon Sep 17 00:00:00 2001 From: Raoul Date: Thu, 23 Jul 2026 10:55:26 +0000 Subject: [PATCH 1/2] Add GitHub CLI to devcontainer with persistent auth Install gh via nix profile alongside the other bootstrap tooling, and persist its credentials across rebuilds with a named volume mounted at ~/.config/gh. Add CONTRIBUTOR.md documenting gh auth and how to create a minimal-permission fine-grained token. --- .devcontainer/Dockerfile | 6 +++- .devcontainer/devcontainer.json | 3 +- CONTRIBUTOR.md | 64 +++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTOR.md diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index edeb0f9..a3fe744 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -56,12 +56,16 @@ ENV PATH=/home/vscode/.nix-profile/bin:/home/vscode/.npm-global/bin:$PATH # so those live in flake.nix's devShell, not here. # - nodejs_22 → host for the Claude Code CLI (run as `claude` from # anywhere, so it stays globally on PATH, not in the shell) +# - gh → GitHub CLI for PRs/issues/auth; global so it's usable +# from anywhere. Auth is persisted across rebuilds via a +# named volume on ~/.config/gh (see devcontainer.json). RUN . /home/vscode/.nix-profile/etc/profile.d/nix.sh \ && nix registry add nixpkgs github:NixOS/nixpkgs/nixos-25.05 \ && nix profile install \ nixpkgs#direnv \ nixpkgs#nix-direnv \ - nixpkgs#nodejs_22 + nixpkgs#nodejs_22 \ + nixpkgs#gh # Claude Code CLI — installed to a per-user prefix so root isn't required. RUN . /home/vscode/.nix-profile/etc/profile.d/nix.sh \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index db3d2a8..8dd1c06 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,13 +9,14 @@ "init": true, "mounts": [ "source=claude-code-config-${devcontainerId},target=/home/vscode/.claude,type=volume", + "source=gh-config-${devcontainerId},target=/home/vscode/.config/gh,type=volume", "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,readonly" ], "containerEnv": { "CLAUDE_CONFIG_DIR": "/home/vscode/.claude", "GIT_CONFIG_GLOBAL": "/home/vscode/.gitconfig.local" }, - "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.claude && bash .devcontainer/setup-git.sh && direnv allow /workspace && nix develop /workspace --command bash -c 'uv sync --frozen'", + "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.claude /home/vscode/.config/gh && bash .devcontainer/setup-git.sh && direnv allow /workspace && nix develop /workspace --command bash -c 'uv sync --frozen'", "customizations": { "vscode": { "extensions": [ diff --git a/CONTRIBUTOR.md b/CONTRIBUTOR.md new file mode 100644 index 0000000..53261c6 --- /dev/null +++ b/CONTRIBUTOR.md @@ -0,0 +1,64 @@ +# Contributing to Komet Node + +## Development environment + +This repository ships a [devcontainer](.devcontainer/) that provisions the full +toolchain (Nix, the flake's `nix develop` shell, the Claude Code CLI, and the +GitHub CLI). Open the repo in a devcontainer-aware editor and everything below is +available out of the box. + +## Using the GitHub CLI (`gh`) + +`gh` is preinstalled in the devcontainer for creating pull requests, reviewing +issues, and other GitHub tasks from the terminal. + +### Authenticating + +Authenticate once with a personal access token: + +```bash +gh auth login +``` + +Choose **GitHub.com** → **HTTPS** → **Paste an authentication token** when +prompted, then paste the token you create below. + +Your credentials are stored in `~/.config/gh` inside the container, which is +backed by a named volume. This means **your token survives container rebuilds** — +you only need to authenticate once, not every time the container is recreated. + +To check or reset your authentication at any time: + +```bash +gh auth status # show the current login +gh auth logout # remove stored credentials +``` + +### Creating a token with minimal permissions + +Prefer **fine-grained personal access tokens** — they let you grant only the +access you actually need, scoped to a single repository, with a short expiry. +Please generate tokens with the **least privilege** required for your work; avoid +broad "classic" tokens with the full `repo` scope unless there is no alternative. + +1. Go to **GitHub → Settings → Developer settings → + [Fine-grained personal access tokens](https://github.com/settings/personal-access-tokens/new)**. +2. Give the token a descriptive name and set the **shortest expiry** that fits + your workflow. +3. Under **Repository access**, choose **Only select repositories** and pick just + `runtimeverification/komet-node` (or your fork) — not "All repositories". +4. Under **Permissions → Repository permissions**, grant only what you need. For a + typical contributor workflow that is: + - **Contents** → *Read and write* (clone, pull, push branches) + - **Pull requests** → *Read and write* (open and update PRs) + - **Issues** → *Read and write* (only if you triage or comment on issues) + + `Metadata → Read` is required and is selected automatically. Leave every other + permission at **No access**. +5. Click **Generate token** and copy it — GitHub shows it only once. Paste it into + the `gh auth login` prompt above. + +> [!TIP] +> Start with the narrowest set of permissions and add more only if a command +> fails with an authorization error. A token that can do less is a smaller risk +> if it ever leaks. From 0de43b8494b471f6119d3353d8ff4fd1d0b2f97f Mon Sep 17 00:00:00 2001 From: Raoul Date: Thu, 23 Jul 2026 11:06:47 +0000 Subject: [PATCH 2/2] Trim gh token section; warn against SSH auth keys in the container Condense the token instructions to the minimal required permissions and add a signing-commits section clarifying that only a signing key (SSH or GPG) belongs in the container -- an SSH authentication key grants full account access and would bypass the fine-grained PAT. --- CONTRIBUTOR.md | 46 ++++++++++++++++++++-------------------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTOR.md b/CONTRIBUTOR.md index 53261c6..ce4d40f 100644 --- a/CONTRIBUTOR.md +++ b/CONTRIBUTOR.md @@ -36,29 +36,23 @@ gh auth logout # remove stored credentials ### Creating a token with minimal permissions -Prefer **fine-grained personal access tokens** — they let you grant only the -access you actually need, scoped to a single repository, with a short expiry. -Please generate tokens with the **least privilege** required for your work; avoid -broad "classic" tokens with the full `repo` scope unless there is no alternative. - -1. Go to **GitHub → Settings → Developer settings → - [Fine-grained personal access tokens](https://github.com/settings/personal-access-tokens/new)**. -2. Give the token a descriptive name and set the **shortest expiry** that fits - your workflow. -3. Under **Repository access**, choose **Only select repositories** and pick just - `runtimeverification/komet-node` (or your fork) — not "All repositories". -4. Under **Permissions → Repository permissions**, grant only what you need. For a - typical contributor workflow that is: - - **Contents** → *Read and write* (clone, pull, push branches) - - **Pull requests** → *Read and write* (open and update PRs) - - **Issues** → *Read and write* (only if you triage or comment on issues) - - `Metadata → Read` is required and is selected automatically. Leave every other - permission at **No access**. -5. Click **Generate token** and copy it — GitHub shows it only once. Paste it into - the `gh auth login` prompt above. - -> [!TIP] -> Start with the narrowest set of permissions and add more only if a command -> fails with an authorization error. A token that can do less is a smaller risk -> if it ever leaks. +Create a **fine-grained** personal access token at **GitHub → Settings → Developer +settings → [Fine-grained personal access tokens](https://github.com/settings/personal-access-tokens/new)** +with the least privilege for your work: + +- **Repository access** → *Only select repositories* → `runtimeverification/komet-node` +- **Contents** → *Read and write* +- **Pull requests** → *Read and write* +- **Issues** → *Read and write* (only if you triage issues) + +`Metadata → Read` is selected automatically; leave everything else at *No access*. + +## Signing commits + +To sign commits made with `git`, add an SSH or GPG key of type **Signing key** to +your GitHub account. + +> [!WARNING] +> Never place an SSH key registered as an **Authentication key** in the container. +> An authentication key grants full account-wide git access and would bypass the +> minimal permissions of your fine-grained PAT. Use a **signing-only** key here.