From 521b2eb6afeccd35be6350bcea901f21f450cc8e Mon Sep 17 00:00:00 2001
From: Denys Vuika <denys.vuika@gmail.com>
Date: Fri, 3 Jul 2026 14:05:52 +0000
Subject: [PATCH] update readme

---
 .devcontainer/README.md | 73 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 69 insertions(+), 4 deletions(-)

diff --git a/.devcontainer/README.md b/.devcontainer/README.md
index dad0b2d295..4bc47b92d8 100644
--- a/.devcontainer/README.md
+++ b/.devcontainer/README.md
@@ -37,6 +37,29 @@ gh auth login
 
 Or export a token instead: `export GH_TOKEN=<your-token>`.
 
+### Verify it works
+
+Run these inside the container terminal, from cheapest to most meaningful:
+
+```bash
+gh --version        # binary installed (no network/auth needed)
+gh auth status      # confirms you are logged in and shows token scopes
+gh api user --jq .login   # end-to-end: hits the API and prints your username
+```
+
+From within the checkout you can also confirm repo access:
+
+```bash
+gh repo view --json nameWithOwner --jq .nameWithOwner
+# → Alfresco/alfresco-ng2-components
+```
+
+One-liner covering install + auth + API:
+
+```bash
+gh --version && gh auth status && gh api user --jq .login
+```
+
 ## Signed Commits With Host Credentials
 
 The VS Code Dev Containers extension handles this automatically — your private
@@ -65,11 +88,53 @@ git commit -S -m "your message"   # -S optional if commit.gpgsign is true
 git push
 ```
 
-### If signing fails
+### Manually importing your public key
 
-- Getting `error: gpg failed to sign the data` / `no secret key`? The agent
-  forwarding didn't attach — **Rebuild Container** or reload the VS Code window.
-- Confirm `gnupg2` is present: `gpg --version`.
+If `git commit -S` fails with `gpg: signing failed: No secret key`, the forwarded
+agent holds your **private** key but the container keyring is missing the matching
+**public** key, so gpg can't locate it. Import it manually.
+
+First, on the **host**, find your real key ID. On macOS, gpg is often `gpg2` and
+may use a different keyring than plain `gpg`, so use the binary that actually holds
+your keys:
+
+```bash
+gpg2 --list-secret-keys --keyid-format=long   # ID is the part after the '/' on the sec line
+git config --global user.signingkey           # what git is set to sign with
+```
+
+Export that key on the **host** into the shared repo checkout (`.git/` is not
+tracked, so it is a safe drop point):
+
+```bash
+# on the HOST — replace with your real key ID
+gpg2 --armor --export <YOUR_KEY_ID> \
+  > /Users/<you>/path/to/alfresco-ng2-components/.git/signing.pub
+```
+
+Import it in the **container** and point git at it:
+
+```bash
+# in the CONTAINER (repo root)
+gpg --import .git/signing.pub && rm .git/signing.pub
+git config --global user.signingkey <YOUR_KEY_ID>
+
+# verify — a passphrase prompt (if any) appears on the HOST, not the container
+gpg --list-secret-keys --keyid-format=long
+echo test | gpg -u <YOUR_KEY_ID> --clearsign
+git commit -S -m "test signed commit"
+```
+
+### Other signing gotchas
+
+- `gpg-connect-agent 'keyinfo --list' /bye` printing **`connection to agent is in
+  restricted mode`** is **normal and good** — VS Code forwards the host's restricted
+  `gpg-agent.extra` socket, which allows signing but blocks key listing. It does not
+  mean the agent is missing.
+- Still failing after importing the public key? The forwarding didn't attach —
+  on the host run `gpgconf --launch gpg-agent` and confirm `echo test | gpg2
+  --clearsign` works there, then **Dev Containers: Rebuild Container**.
+- Confirm `gnupg2` is present in the container: `gpg --version`.
 - The automatic gitconfig / GPG / SSH forwarding is a feature of the **VS Code
   Dev Containers extension**. If you run this config via the plain
   `@devcontainers/cli`, you must mount `~/.gnupg`, `~/.gitconfig`, and the agent