@@ -24,6 +24,11 @@ git config --global user.email "you@example.com"
 
 If `ssh-add -L` shows no keys, commit signing inside the devcontainer will fail.
 
+If the environment creating the devcontainer has no Git config to hand over, set `GIT_USER_NAME` and
+`GIT_USER_EMAIL` in that environment instead; [`devcontainer.json`](./devcontainer.json) forwards
+both through `${localEnv:...}` and `post-create.sh` writes them into the container's global Git
+config. Configured Git config always wins over these variables.
+
 ### VS Code
 
 1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
@@ -43,31 +48,66 @@ bash -ic 'complete -p task >/dev/null && echo task completion ok'
 docker version
 gh --version
 git config --get gpg.format
-git config --get user.signingkey
 ssh-add -L
 ```
 
 Expected Git signing values:
 
 ```bash
-git config --get gpg.format         # ssh
-git config --get commit.gpgsign    # true
-git config --get user.signingkey   # /home/vscode/.ssh/devcontainer_signing_key.pub
+git config --get gpg.format                # ssh
+git config --get commit.gpgsign            # true
+git config --get gpg.ssh.defaultKeyCommand # ssh-add -L
+git config --get gpg.ssh.allowedSignersFile # /home/vscode/.config/git/allowed_signers
 ```
 
+`user.signingkey` is set only when an agent key comment matches your Git email; otherwise it stays
+unset and the key is read from the agent at commit time.
+
 ## How SSH Signing Works Here
 
 The devcontainer uses SSH commit signing, not GPG keyring-based signing.
 
-- [`post-create.sh`](./post-create.sh) bootstraps Git identity and calls the signing sync helper
-- [`sync-signing-key.sh`](./sync-signing-key.sh) reads the forwarded SSH agent and refreshes:
-  - `${HOME}/.ssh/devcontainer_signing_key.pub`
-  - `${HOME}/.config/git/allowed_signers`
-- [`devcontainer.json`](./devcontainer.json) runs the helper on:
-  - `postCreateCommand`
-  - `postStartCommand`
+Most of it is plain Git configuration rather than shell logic:
+
+```bash
+commit.gpgsign=true                    # every commit is signed
+gpg.format=ssh                         # signed with an SSH key
+gpg.ssh.defaultKeyCommand="ssh-add -L" # the key comes from the live agent
+```
+
+With those three set, Git signs with whatever the agent currently holds, and refuses to commit
+when it holds nothing. No key is cached anywhere, so there is nothing to go stale when a
+reconnect changes the forwarded socket or the loaded key.
+
+[`sync-signing-key.sh`](./sync-signing-key.sh) applies that baseline and adds the one thing Git
+cannot derive on its own: `${HOME}/.config/git/allowed_signers`, which maps the Git email to the
+keys currently in the agent so `git log --show-signature` can verify. It runs from
+[`post-start.sh`](./post-start.sh) on every start, and can be run by hand at any time.
+
+If one of the agent keys has a comment containing your Git email, that key is pinned as
+`user.signingkey` so selection does not depend on agent order. With no such key the pin is left
+unset, which is both simpler and immune to going stale. A signing key you configured yourself is
+never overwritten.
+
+[`post-create.sh`](./post-create.sh) does not configure signing. Creating the environment,
+personalizing Git, and having credentials available are three separate things, and only the first
+has to succeed for the container to be usable.
+
+### When No Agent Has Attached Yet
+
+A devcontainer can be created before any interactive session attaches, for example by
+`devcontainer up` from the Dev Containers CLI, or by a platform that personalizes the workspace
+afterwards. No SSH agent is forwarded at that point, and no Git identity may exist yet. Neither is
+treated as a failure to create the environment: the hooks report what is missing and finish.
 
-This keeps the configured public key file aligned with the currently forwarded agent key.
+Signing is not relaxed to achieve that. `commit.gpgsign` is on from the start, so a commit without
+a usable key fails:
+
+```text
+fatal: either user.signingkey or gpg.ssh.defaultKeyCommand needs to be configured
+```
+
+Nothing else in the environment needs a key, so builds, tests and the E2E suite run regardless.
 
 ## Best Practices
 
@@ -96,18 +136,24 @@ workflows.
 3. Keep signing setup in one small script
    This repo uses [`sync-signing-key.sh`](./sync-signing-key.sh) for that reason.
 
-4. Prefer deterministic key selection
-   The helper first looks for an SSH key whose comment matches `git user.email`.
-   If none matches, it falls back to the first key from `ssh-add -L`.
+4. Prefer standard Git mechanisms over shell logic
+   `gpg.ssh.defaultKeyCommand` selects the key whenever no comment matches the Git email, so there
+   is usually no pinned key to become stale.
 
-5. Keep signing and verification data in sync
-   `user.signingkey` and `gpg.ssh.allowedSignersFile` are regenerated together.
+5. Trust every key the agent currently holds
+   `allowed_signers` lists them all under the Git email, so verification works whichever one the
+   key command picks.
 
 6. Store only public key material in the container
    The private key stays on the host and is accessed through the forwarded SSH agent.
 
-7. Fail early with actionable messages
-   Missing agent, missing keys, or missing Git identity should stop setup immediately.
+7. Report, do not fail
+   A missing identity or agent is diagnosed and setup continues. Git, not a shell script, is what
+   refuses an unsigned commit.
+
+8. Use the Git email as the `allowed_signers` principal
+   That file takes bare identities, so a `Name <email>` principal makes `ssh-keygen -Y verify`
+   report `invalid key` and `No principal matched` for a correctly signed commit.
 
 ### General Devcontainer Maintenance
 
@@ -123,9 +169,8 @@ workflows.
 ```bash
 echo "$SSH_AUTH_SOCK"
 ssh-add -L
-cat ~/.ssh/devcontainer_signing_key.pub
 cat ~/.config/git/allowed_signers
-git config --show-origin --get user.signingkey
+git config --show-origin --get-regexp '^(commit\.gpgsign|gpg\.)'
 ```
 
 ## Optional `.env` for `gh`
@@ -151,6 +196,10 @@ Recommended token scopes:
 
 The repo-root `.env` must stay local. It is already gitignored.
 
+Alternatively just run `gh auth login` once. `~/.config/gh` is a named volume (`ghconfig`), so the
+login survives container rebuilds; the first rebuild after this mount was added starts from an
+empty volume and needs one more login.
+
 ## Troubleshooting
 
 ### Commit Signing Fails
@@ -159,8 +208,8 @@ Check:
 
 ```bash
 ssh-add -L
-cat ~/.ssh/devcontainer_signing_key.pub
-git config --get user.signingkey
+git config --get commit.gpgsign
+git config --get gpg.ssh.defaultKeyCommand
 ```
 
 Then refresh the signing setup manually:
@@ -173,15 +222,26 @@ Common causes:
 
 - no host `ssh-agent` running
 - no key loaded into the host agent
-- the forwarded agent key changed after the container was created
 - `user.name` or `user.email` is missing
 
-Typical signing error when the configured public key is stale:
+Typical error when no key is reachable:
 
 ```text
-error: No private key found for public key "/home/vscode/.ssh/devcontainer_signing_key.pub"?
+fatal: either user.signingkey or gpg.ssh.defaultKeyCommand needs to be configured
 ```
 
+### Commits Sign But Do Not Verify
+
+```text
+allowed_signers:1: invalid key
+No principal matched.
+```
+
+The principal in `~/.config/git/allowed_signers` is malformed. Each line is
+`<email> <keytype> <key> [comment]`; re-run `bash .devcontainer/sync-signing-key.sh` to regenerate
+it. Verify with `git log -1 --show-signature`, and check the helper itself with
+`bash .devcontainer/test-signing.sh`.
+
 ### Push Fails But Commit Signing Works
 
 Commit signing and Git push authentication are separate concerns.
@@ -213,7 +273,9 @@ Usually normal. Rebuild time mostly depends on tool installation and cache reuse
 - [`Dockerfile`](./Dockerfile) - Multi-stage container image
 - [`devcontainer.json`](./devcontainer.json) - VS Code devcontainer configuration
 - [`post-create.sh`](./post-create.sh) - Initial bootstrap
+- [`post-start.sh`](./post-start.sh) - Per-start refresh
 - [`sync-signing-key.sh`](./sync-signing-key.sh) - SSH signing refresh helper
+- [`test-signing.sh`](./test-signing.sh) - Tests for the signing helper, using a disposable key
 - [`README.md`](./README.md) - This document
 
 ## References
 
@@ -97,6 +97,9 @@
     "source=codexconfig,target=/home/vscode/.codex,type=volume",
     "source=claudeconfig,target=/home/vscode/.claude,type=volume",
     "source=dotkube,target=/home/vscode/.kube,type=volume",
+    // Keeps the gh CLI logged in across rebuilds. Without it every rebuild drops
+    // ~/.config/gh and gh asks for `gh auth login` again.
+    "source=ghconfig,target=/home/vscode/.config/gh,type=volume",
     "source=persisted-home,target=/home/vscode/persisted-home,type=volume"
   ],
   "containerEnv": {
 
@@ -6,15 +6,13 @@ log() {
   echo "[post-create] $*"
 }
 
-fail() {
-  echo "[post-create] ERROR: $*" >&2
-  exit 1
-}
-
 workspace_dir="${1:-${containerWorkspaceFolder:-${WORKSPACE_FOLDER:-$(pwd)}}}"
 log "Using workspace directory: ${workspace_dir}"
 
-# Resolve Git identity from effective config first, then fallback env vars.
+# Git identity is developer personalization, not part of building a usable
+# development environment, so its absence is reported and not fatal. Whatever
+# created this container (VS Code copying the host Git config, a platform's own
+# personalization step) may supply it before, during or after this hook.
 git_name="$(git config --get user.name || true)"
 git_email="$(git config --get user.email || true)"
 
@@ -26,21 +24,23 @@ if [ -z "${git_email}" ] && [ -n "${GIT_USER_EMAIL:-}" ]; then
   git_email="${GIT_USER_EMAIL}"
 fi
 
-if [ -z "${git_name}" ] || [ -z "${git_email}" ]; then
-  fail "Missing Git identity. Set user.name and user.email in Git, or provide GIT_USER_NAME and GIT_USER_EMAIL to the devcontainer environment."
-fi
-
-# Persist identity globally in the container if it is not already configured there.
-if ! git config --global --get user.name >/dev/null 2>&1; then
+if [ -n "${git_name}" ] && [ -z "$(git config --global --get user.name || true)" ]; then
   git config --global user.name "${git_name}"
 fi
 
-if ! git config --global --get user.email >/dev/null 2>&1; then
+if [ -n "${git_email}" ] && [ -z "$(git config --global --get user.email || true)" ]; then
   git config --global user.email "${git_email}"
 fi
 
-log "Refreshing Git SSH signing configuration"
-bash "${workspace_dir}/.devcontainer/sync-signing-key.sh"
+if [ -z "${git_name}" ] || [ -z "${git_email}" ]; then
+  log "WARNING: no Git identity yet. Set user.name and user.email, or provide GIT_USER_NAME and"
+  log "WARNING: GIT_USER_EMAIL to the devcontainer environment. Commits need one; the rest of the"
+  log "WARNING: environment does not, so setup continues."
+fi
+
+# Signing is not configured here. post-start.sh runs on every start, including
+# the first one right after this hook, and that is where an SSH agent can
+# actually be expected to exist.
 
 log "Ensuring Go cache directories exist"
 sudo mkdir -p \
 
@@ -4,7 +4,12 @@ set -euo pipefail
 
 workspace_dir="${1:-${containerWorkspaceFolder:-${WORKSPACE_FOLDER:-$(pwd)}}}"
 
-bash "${workspace_dir}/.devcontainer/sync-signing-key.sh"
+# Refresh signing on every start: this is the first hook that can expect a
+# forwarded SSH agent, and a reconnect can change SSH_AUTH_SOCK or the loaded
+# key. The helper reports missing credentials rather than failing, and Git
+# itself is what refuses an unsigned commit, so startup never depends on them.
+bash "${workspace_dir}/.devcontainer/sync-signing-key.sh" ||
+  echo "[post-start] WARNING: sync-signing-key.sh failed; run it by hand to see why." >&2
 
 if [[ ! -f "${workspace_dir}/.env" ]]; then
   echo "hint: ${workspace_dir}/.env is absent; add GH_TOKEN there if you want read-only gh CLI access."