GitHub App

GitHub Action mode is the primary zero-server path for consumer repositories. Use gpustack/loopwright@main for scheduled runs, manual dispatch, and /loopwright comment commands.

The resident HTTP daemon is disabled by default. Operators can opt in for centralized webhook queuing and token brokering; production requires separately qualified ingress and host infrastructure.

Contents

• App registration
• Admission and permissions
• GitHubAppConfig
• Control plane
• Host qualification

App registration

Create a GitHub App in your personal Developer settings or organization settings (https://github.com/organizations/<org>/settings/apps), then install it on the target repositories.

Use actions/create-github-app-token@v1 with gpustack/loopwright@main in the consumer workflow . The App’s webhook secret and private key must also be available in the trusted daemon environment when enabled.

Admission and permissions

Subscribe only to the event types used by your taskpack, including release, issue comment and pull request review as needed. Comment commands are restricted to authorized actors. Verify X-Hub-Signature-256 over raw request bytes with HMAC-SHA256; mismatches and conflicting delivery IDs fail closed. The receiver implements verification before intake.

Installation tokens are restricted to one repository. The read_only profile grants contents and metadata read; publish_pull_request grants contents and pull requests write plus metadata read. Store the App private key and webhook secret in trusted host secret storage.

GitHubAppConfig

Save the daemon configuration as github-app.yaml:

apiVersion: loopwright.dev/v1alpha1
kind: GitHubAppConfig
spec:
  appId: '12345'
  webhookSecretEnv: LOOPWRIGHT_WEBHOOK_SECRET
  privateKeyEnv: LOOPWRIGHT_APP_PRIVATE_KEY
  apiBaseUrl: https://api.github.com # Optional (defaults to https://api.github.com)
  listen: # Optional block (set enabled to true for loopwright app-serve)
    enabled: false # Optional (defaults to false)
    host: 127.0.0.1
    port: 8787
    webhookPath: /webhooks/github # Optional (defaults to /webhooks/github)
  tokenTtlSeconds: 600 # Optional (defaults to 600)
  maxPayloadBytes: 1048576 # Optional (defaults to 1048576)
  taskpackPath: .loopwright/taskpack.yaml # Optional repo-relative taskpack path
  operatorAllowlist: # Optional GitHub login allowlist for slash commands
    - release-operator

• Secrets: Provide environment variable names, not secret values.
• Listen: Add authenticated ingress before serving external webhooks.
• Path: The taskpack path must be relative and cannot traverse directories.

Control plane

Set spec.listen.enabled: true, bind the named secrets in the trusted environment, then start the daemon:

loopwright app-serve --config github-app.yaml --repo .

The command applies the configured listener and token broker settings. It refuses disabled or invalid configuration. The loader resolves the named webhook secret and private key from the environment.

The service binds loopback by default. Provide authenticated ingress and a configured broker in the trusted host; do not expose tenant lease endpoints publicly. Endpoints include the configured listen.webhookPath (default /webhooks/github), /healthz, and tenant lease and settle routes. The broker issues scoped short-lived tokens and scrubs secrets from responses.

Webhook events

Intake dispositions

Host qualification

Verify the host against the runtime baseline and required sandbox backends before starting app-serve. Interactive MCP OAuth challenges and unsandboxed fallbacks fail closed (MCP_OAUTH_UNSUPPORTED, SANDBOX_BACKEND_UNAVAILABLE, SANDBOX_CAPABILITY_INSUFFICIENT).

In-memory queue and delivery state do not establish durable cross-restart recovery.