Sync Worker

The sync worker keeps your oidc.pub service in sync with your OIDC issuer by periodically fetching the discovery document and JWKS from the source and uploading them to oidc.pub. We provide a dedicated Docker image (registry.gitlab.com/oidc.pub/cli:latest-sync) that makes it easy to embed in your infrastructure for automated synchronization. For interactive use and service management, see the CLI documentation.

Quick start

docker run -d --name oidcpub-sync \
  -e OIDC_SOURCE_URL=https://your-issuer.internal \
  -e OIDCPUB_SERVICE_ID=<your-service-subdomain> \
  -e OIDCPUB_API_KEY=<your-api-key> \
  registry.gitlab.com/oidc.pub/cli:latest-sync

The worker syncs on startup and then every 300 seconds by default. When running inside a Kubernetes cluster, it auto-detects the API server address — no OIDC_SOURCE_URL needed.

Kubernetes

For Kubernetes clusters, the worker can be deployed with a single command. It discovers the API server automatically via the in-cluster service account.

kubectl run oidcpub-sync \
  --namespace=kube-system \
  --image=registry.gitlab.com/oidc.pub/cli:latest-sync \
  --env="OIDCPUB_SERVICE_ID=<your-service-subdomain>" \
  --env="OIDCPUB_API_KEY=<your-api-key>"

One-shot mode

Pass --once to sync a single time and exit. One-shot mode is also enabled automatically when CI=true is set in the environment, which most CI/CD systems (GitLab CI, GitHub Actions, etc.) do by default.

docker run --rm \
  -e OIDC_SOURCE_URL=https://your-issuer.internal \
  -e OIDCPUB_SERVICE_ID=<your-service-subdomain> \
  -e OIDCPUB_API_KEY=<your-api-key> \
  registry.gitlab.com/oidc.pub/cli:latest-sync \
  --once

Authentication

The sync worker supports two methods to authenticate with the oidc.pub API:

  • Static API key — set OIDCPUB_API_KEY. Simplest option, recommended for most setups. Obtain an API key from the oidc.pub dashboard under your service settings.
  • OIDC token — set OIDCPUB_OIDC_TOKEN_PATH to a projected token file. The worker authenticates to the oidc.pub API using an OIDC token from the issuer being synced.

Self-referential updates: Using OIDC authentication from the same service you are syncing is possible but carries risk: if a key rotation goes wrong and the updated JWKS is pushed with an invalid key, the worker can no longer authenticate to push a fix. A static API key avoids this chicken-and-egg problem entirely.

Environment variables

  • OIDCPUB_SERVICE_ID — your oidc.pub service subdomain (required)
  • OIDCPUB_API_KEY — static API key from the dashboard
  • OIDCPUB_OIDC_TOKEN_PATH — path to an OIDC token file (alternative to API key)
  • OIDCPUB_SERVICE_URL — service URL (default: https://oidc.pub). Set to https://staging.oidc.pub for staging.
  • SYNC_INTERVAL — seconds between syncs (default: 300)
  • OIDC_SOURCE_URL — base URL to fetch OIDC config from. Auto-detected when running inside a Kubernetes cluster.
  • CI — when set to true, enables one-shot mode automatically. Set by most CI/CD systems.