GitHub App and webhook

Each host uses a private GitHub App to watch the queue and register runners. ushr creates the App for you from a manifest.

Permissions

Org App (--org)Actions: read · Metadata: read · Organization self-hosted runners: write
Repo App (--repo)Actions: read · Metadata: read · Administration: write

GitHub has no repo-level self-hosted runner permission. Repo-level runners need Administration: write.

The agent finds the App installation by itself. You only keep the App ID and the private key path in agent.yaml.

Telemetry on the hosted plane

ushr login creates the App with a webhook to the control plane. The webhook has its own secret and subscribes to Workflow job events. You do not configure anything.

The dashboard combines dispatch records with these signed events. Start events give live job links. Completion events give workflow names, results and run times.

Telemetry on a self-hosted controller

ushr setup creates the App with its webhook turned off. To record job results, do these steps:

  • Add a webhook secret to controller.yaml.
  • Make the controller reachable from GitHub, for example through a tunnel or a reverse proxy.
  • In the GitHub App settings, turn the webhook on. Set the URL to https://YOUR_HOST/webhook and use the same secret.
  • Subscribe the App to Workflow job events.
webhook:
  secret: "a-long-random-string"
  ledger_path: ""   # empty = default job ledger path
webhook.secretHMAC secret. Empty turns the receiver off. The USHR_WEBHOOK_SECRET environment variable overrides it.
webhook.ledger_pathWhere completed jobs are recorded. Empty uses the default path.
ushr cost reads the same job ledger. Without the webhook, run ushr cost --backfill to scan GitHub history instead.

next Drivers →