Skip to content
Get Started
Quickstart (local)

Quickstart (local)

Local development only, not for production
This page configures github-sts for speed of setup, not for safety. TLS is off and replay protection does not survive a restart. See how to deploy for production →

Already have a GitHub App from Configure a GitHub App and Install the App? This pulls the published image and runs it on your own machine with settings chosen for setup speed, not production use, so you can get the server up and verified in a few minutes.

Prerequisites

  • Docker (or another OCI-compatible container runtime)
  • A GitHub App you can install on a test organization
  • The App’s private key as a .pem file

Configuration 

# LOCAL DEVELOPMENT ONLY, NOT FOR PRODUCTION.
export GITHUBSTS_APP_DEFAULT_APP_ID="123456"
export GITHUBSTS_APP_DEFAULT_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
export GITHUBSTS_OIDC_ALLOWED_ISSUERS="https://token.actions.githubusercontent.com"
export GITHUBSTS_OIDC_REQUIRED_AUDIENCE="https://sts.example.com"
export GITHUBSTS_BUNDLE_ENFORCEMENT="optional"

Start the server 

docker run -d --name github-sts-local -p 8080:8080 \
  -e GITHUBSTS_APP_DEFAULT_APP_ID \
  -e GITHUBSTS_APP_DEFAULT_PRIVATE_KEY \
  -e GITHUBSTS_OIDC_ALLOWED_ISSUERS \
  -e GITHUBSTS_OIDC_REQUIRED_AUDIENCE \
  -e GITHUBSTS_BUNDLE_ENFORCEMENT \
  ghcr.io/depthmark/github-sts:latest

Building from source instead of pulling the published image? Run docker build -t github-sts:local . from the repository root, then swap the image name in the docker run command above.

Verify it’s running 

curl -s http://127.0.0.1:8080/health
# Includes liveness, security posture, and bundle state

Check the logs:

docker logs github-sts-local

With no GITHUBSTS_JTI_BACKEND set, the server defaults to the in-memory JTI backend, and the logs carry a warning on every start: in-memory JTI cache does not survive restarts and is not shared across replicas; consider redis for production. That warning is not noise: replay protection resets whenever the container restarts.

When you’re done, stop and remove the container:

docker rm -f github-sts-local

Next

This page only gets the server running: it does not exchange a token, because that requires a real OIDC token from an identity provider, which this quickstart does not mint. See Generate a token for how to request an OIDC token from a GitHub Actions workflow and exchange it here.

This container also runs with no TLS, no Redis, and no autoscaling; it’s for trying github-sts, not running it. For a real deployment, see the Helm chart quickstart and Kubernetes.

Generate a token