serversideup/github-cli
Run GitHub CLI anywhere with a lightwieght and powerful Docker image.
1.1K
serversideup/github-cli
is a lightweight solution for running GitHub CLI via Docker.
Getting started is easy. Here's a few tips on how to use this image.
Our images are available on Docker Hub and GitHub Container Registry 🥳
DockerHub:
GitHub Container Registry:
There are a few directories that we need to mount to ensure everything works correctly.
Mounting the /config
directory
In order to authenticate with GitHub, we need to mount your ~/.config
directory from your host into the container. We have a special /config
directory that is symbolically linked from the unprivileged user's home directory. We use this root directory so you can change the RUN_AS_USER
environment variable and not have to worry about having to predict what the absolute path to the configuration directory is.
For example, if you rename the RUN_AS_USER
to something like bob
, /home/bob/.config
will be symbolically linked to /config
, giving you a predictable path to mount your configuration files.
Working with SSH
SSH also behaves in a similar way. Keep reading below for more details.
Mounting the /app
directory
We also have a /app
directory that is intended for you your workspace.
docker run --rm -it \
-v "$HOME/.ssh:/ssh:ro" \
-v "$HOME/.ssh/known_hosts:/ssh/known_hosts:rw" \
-v "$(pwd):/app" \
-v "$HOME/.config/gh:/config/gh:rw" \
-e "PUID=9999" \
-e "PGID=9999" \
-e "RUN_AS_USER=bob" \
serversideup/github-cli:latest gh --version
docker run --rm -it \
-v "$HOME/.ssh:/ssh" \
-v "$(pwd):/app" \
serversideup/github-cli:latest /bin/sh
NoteWorking with SSH keys can be tricky, especially if we're setting a `RUN_AS_USER` dynamically. We created a few things to help reduce the headache of getting this configured.
The /ssh
directory
By default, we have a /ssh
directory that is symbolically linked from ~/.ssh
. The /ssh
directory is used as our single source of truth for SSH keys and configurations.
If you set RUN_AS_USER
, the entrypoint will create a home directory at /home/${RUN_AS_USER}
, then create a symbolic link from /home/${RUN_AS_USER}/.ssh
to /ssh
. This gives you the power to set your RUN_AS_USER
to anything you want without us needing to predict what user you want to run as.
Mounting the SSH auth socket
The SSH auth socket is a Unix socket used by the SSH agent to communicate with other processes, allowing for secure key management. To use it with Docker, you can mount it as follows:
macOS:
docker run --rm -it \
-v "$HOME/.ssh:/ssh:ro" \
-v "$HOME/.ssh/known_hosts:/ssh/known_hosts:rw" \
-v "$(pwd):/app" \
-v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock" \
-e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" \
serversideup/github-cli:latest gh --version
Notice how we're matching the SSH_AUTH_SOCK
to the host's socket. This is necessary for the SSH agent to communicate with the container.
Linux:
docker run --rm -it \
-v "$HOME/.ssh:/ssh:ro" \
-v "$HOME/.ssh/known_hosts:/ssh/known_hosts:rw" \
-v "$(pwd):/app" \
-v "$SSH_AUTH_SOCK:$SSH_AUTH_SOCK" \
-e SSH_AUTH_SOCK=$SSH_AUTH_SOCK" \
serversideup/github-cli:latest gh --version
You can customize the image easily with the following environment variables:
Variable | Default | Description |
---|---|---|
PUID | 1000 | Set the User ID that you'd like to run GitHub CLI as |
PGID | 1000 | Set the Group ID that you'd like to run GitHub CLI as |
RUN_AS_USER | github | The username you'd like to run GitHub CLI as (this will be created for you and will default to an unprivileged user) |
DEBUG | false | Enable debug output of container startup |
As an open-source project, we strive for transparency and collaboration in our development process. We greatly appreciate any contributions members of our community can provide. Whether you're fixing bugs, proposing features, improving documentation, or spreading awareness - your involvement strengthens the project. Please review our code of conduct to understand how we work together respectfully.
Need help getting started? Join our Discord community and we'll help you out!
All of our software is free an open to the world. None of this can be brought to you without the financial backing of our sponsors.
Bronze Sponsors
No bronze sponsors yet. Become a sponsor →Individual Supporters
We're Dan and Jay - a two person team with a passion for open source products. We created Server Side Up to help share what we learn.
If you appreciate this project, be sure to check out our other projects.
docker pull serversideup/github-cli