enponsba/github-token repository overview

⁠Quick reference

• Maintained by: enponsba⁠
• Where to get help: GitHub Issues⁠
• Where to file issues: GitHub Issues⁠
• Source: github-token⁠

⁠Supported tags

Tags follow the pattern <python>-<distro> for every actively maintained⁠ CPython version. End-of-life versions are removed automatically.

All tags are published for linux/amd64 and linux/arm64.

See the Tags tab⁠ for the full list of currently available images.

⁠What is github-token?

A minimal Docker image that generates short-lived GitHub App installation tokens⁠. Replace inline bash JWT generation in your Kubernetes jobs and CI pipelines with a single container invocation.

Zero external Python dependencies. The image contains only CPython and the application source code.

⁠How it works

1. Reads the GitHub App private key from a file or environment variable.
2. Constructs an RS256-signed JWT using only the Python standard library.
3. Exchanges the JWT for a short-lived installation access token via the GitHub API.
4. Outputs the token to stdout, a file, or $GITHUB_OUTPUT.

⁠How to use this image

The private key can be provided in two ways:

1. As an environment variable (GITHUB_APP_PRIVATE_KEY) -- pass the PEM string directly. No volume mount required.
2. As a file path (GITHUB_APP_PRIVATE_KEY_PATH) -- mount the PEM file into the container. Defaults to /etc/github/GITHUB_APP_PRIVATE_KEY.

If both are set, the environment variable takes precedence.

⁠Pass the key as an environment variable

docker run --rm \
  -e GITHUB_APP_ID=12345 \
  -e GITHUB_APP_INSTALLATION_ID=67890 \
  -e GITHUB_APP_PRIVATE_KEY="$(cat /path/to/key.pem)" \
  enponsba/github-token:latest

The token is printed to stdout.

⁠Pass the key as a mounted file

docker run --rm \
  -e GITHUB_APP_ID=12345 \
  -e GITHUB_APP_INSTALLATION_ID=67890 \
  -v /path/to/key.pem:/etc/github/GITHUB_APP_PRIVATE_KEY:ro \
  enponsba/github-token:latest

⁠Scoped permissions

Request only the permissions you need:

docker run --rm \
  -e GITHUB_APP_ID=12345 \
  -e GITHUB_APP_INSTALLATION_ID=67890 \
  -e GITHUB_APP_PRIVATE_KEY="$(cat /path/to/key.pem)" \
  -e GITHUB_TOKEN_PERMISSIONS='{"contents":"read","pull_requests":"write"}' \
  -e GITHUB_TOKEN_REPOSITORIES='my-repo,other-repo' \
  enponsba/github-token:latest

⁠Writing the token to a file

docker run --rm \
  -e GITHUB_APP_ID=12345 \
  -e GITHUB_APP_INSTALLATION_ID=67890 \
  -e GITHUB_APP_PRIVATE_KEY="$(cat /path/to/key.pem)" \
  -e GITHUB_TOKEN_OUTPUT=file:/shared/token \
  -v /tmp/shared:/shared \
  enponsba/github-token:latest

⁠Kubernetes init container

Use as an init container to provide a token to your main workload. The private key can be injected directly from a Secret as an environment variable -- no volume mount for the key is needed:

initContainers:
  - name: get-token
    image: enponsba/github-token:latest
    env:
      - name: GITHUB_APP_ID
        valueFrom:
          secretKeyRef:
            name: github-app-secret
            key: GITHUB_APP_ID
      - name: GITHUB_APP_INSTALLATION_ID
        valueFrom:
          secretKeyRef:
            name: github-app-secret
            key: GITHUB_APP_INSTALLATION_ID
      - name: GITHUB_APP_PRIVATE_KEY
        valueFrom:
          secretKeyRef:
            name: github-app-secret
            key: GITHUB_APP_PRIVATE_KEY
      - name: GITHUB_TOKEN_OUTPUT
        value: "file:/shared/token"
    volumeMounts:
      - name: shared
        mountPath: /shared

Complete examples: Kubernetes Job⁠ | ArgoCD PostSync hook⁠

⁠Environment variables

Either GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_PATH must be provided. If both are set, the literal key string takes precedence.

⁠Output modes

⁠Image variants

⁠slim (default)

Based on Debian python:<version>-slim. Recommended for most use cases.

⁠alpine

Based on python:<version>-alpine. Smaller image at the cost of musl libc instead of glibc. Use when image size is the primary concern.

⁠Architecture support

All images are multi-platform manifests supporting:

• linux/amd64
• linux/arm64

⁠Security

• The container runs as the nobody user (non-root).
• No external Python dependencies -- only the standard library is used.
• Tokens are short-lived (1 hour) and scoped to the requested permissions.
• The private key is never written to stdout or logs.

For security concerns, see the security policy⁠.

⁠License

Apache License 2.0⁠