| 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
- Keep the configuration mount writable so
gh auth login persists authentication between container runs.
- Do not create credentials or tokens automatically. Authentication is initiated explicitly by
gh auth login or supplied through GitHub CLI's standard environment variables.
- Keep archive installation inside
../../../images/gh_2_94/Containerfile; the version shim should only coordinate local image selection and runtime behavior.
- 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.
- Treat
GH_TOKEN and other credentials as secrets; do not add them to logs, fixtures, or documentation examples.
- 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.
