shimmy-tool-gh

name	shimmy-tool-gh
description	Guidance for using, changing, testing, and troubleshooting the GitHub CLI shim in this repository, including persistent authentication configuration and GH_* environment forwarding.

GitHub CLI Shim

Use this skill when working with shims/gh, its tests, its docs, or GitHub CLI usage through Shimmy.

Files

• Kind dispatcher: ../../../shims/gh
• Version shim: ../../../shims/gh_2_94
• User docs: ../../../docs/shims/gh.md
• Tests: ../../../scripts/test-shimmy.sh
• Catalog: ../../../lib/repo/shimmy-catalog.sh
• Lifecycle scripts: ../../../scripts/status-shimmy.sh and ../../../scripts/update-shimmy.sh

Current Behavior

• Default image: locally built localhost/shimmy-gh-2_94:<context-hash>-<platform>
• Image override: SHIMMY_GH_IMAGE
• Build override: SHIMMY_GH_IMAGE_BUILD=always
• Pull override for image overrides: SHIMMY_GH_IMAGE_PULL=always
• Base image override: SHIMMY_GH_BASE_IMAGE, defaulting to alpine:3.22
• GitHub CLI release override: SHIMMY_GH_VERSION, defaulting to 2.94.0
• Host config: GH_CONFIG_DIR, defaulting to $HOME/.config/gh
• Container config: /home/gh/.config/gh, set through GH_CONFIG_DIR
• Mounts: $PWD to /work and the host config directory read-write to the container config directory
• Forwarded environment: GH_*; the container GH_CONFIG_DIR value always points at the mounted path
• Runtime mode: TTY only when stdin and stdout are terminals

Change Rules

1. Keep the configuration mount writable so gh auth login persists authentication between container runs.
2. Do not create credentials or tokens automatically. Authentication is initiated explicitly by gh auth login or supplied through GitHub CLI's standard environment variables.
3. Keep archive installation inside ../../../images/gh_2_94/Containerfile; the version shim should only coordinate local image selection and runtime behavior.
4. Keep the local image tied to an official GitHub CLI release archive. Update the kind/version name, catalog, status, update behavior, docs, and tests together when changing versions.
5. Treat GH_TOKEN and other credentials as secrets; do not add them to logs, fixtures, or documentation examples.
6. Use non-mutating validation commands such as gh --version, gh auth status, gh pr list, and gh repo view unless the user explicitly requests a write.

Validation

• Preview: ./shims/gh --preview-shim --version
• Direct smoke: ./shims/gh --version
• Auth inspection: gh auth status

Learning Guidance

• Keep GitHub CLI authentication state in GH_CONFIG_DIR so it is independent of the image user's home directory.
• The local image must include git, because GitHub CLI uses it to discover and operate on local repositories.
• If a Shimmy wrapper fails because of Podman reachability, sandboxing, or AI Agent approval symptoms, use the Shimmy escalation workflow before falling back to a host-installed tool.