witnora

Hosted GitHub App v0.1

The Witnora GitHub App is an optional authorization layer for repository setup. It does not replace the customer-owned Runner, and it never receives a personal access token.

What it can do

• discover only repositories selected during installation;
• open a reviewable branch and pull request containing allowlisted Witnora integration files;
• encrypt a project-scoped Witnora API key with GitHub’s Actions public key;
• write WITNORA_PROJECT_ID as an Actions variable;
• dispatch an existing allowlisted Witnora workflow;
• retain an operation record without storing file contents or plaintext credentials.

It cannot merge pull requests, change branch protection, write arbitrary files, read Actions secret values, or access repositories outside the installation.

Registration

Register the App under the Witnora GitHub account with:

• Homepage: https://witnora.com
• Callback URL: https://witnora.com/v1/github/install/callback
• Request user authorization during installation: enabled
• Webhook URL: https://witnora.com/v1/github/webhooks
• Webhook secret: a new random value stored only in GitHub and Render
• Public App: disabled for internal acceptance; enable only after acceptance

Repository permissions:

• Actions: read and write
• Contents: read and write
• Metadata: read
• Pull requests: read and write
• Secrets: read and write
• Variables: read and write
• Workflows: read and write

Subscribe only to installation and installation_repositories events.

GitHub warns that the installation callback’s installation_id can be spoofed. Witnora therefore requires installation-time user authorization, exchanges the one-time OAuth code, verifies that the installation belongs to that GitHub user, and discards the user token immediately. The App then uses short-lived installation tokens for repository operations.

Render secrets

Set all variables together; partial configuration stops startup:

WITNORA_GITHUB_APP_ID
WITNORA_GITHUB_APP_SLUG
WITNORA_GITHUB_APP_CLIENT_ID
WITNORA_GITHUB_APP_CLIENT_SECRET
WITNORA_GITHUB_APP_PRIVATE_KEY
WITNORA_GITHUB_APP_WEBHOOK_SECRET
WITNORA_GITHUB_APP_STATE_SECRET

WITNORA_GITHUB_APP_PRIVATE_KEY accepts PEM text or base64-encoded PEM. Generate the state secret independently with at least 32 random bytes. Never reuse the webhook secret, client secret, Witnora signing key, or API key.

Safety boundaries

• Installation state is HMAC signed and expires after ten minutes.
• The callback rechecks the Witnora actor’s current owner/admin role.
• One GitHub installation can bind to only one Witnora project.
• Repository access is refreshed from GitHub and capped at 100 selected repos; larger installations fail visibly instead of returning a partial allowlist.
• PR writes allow at most four fixed Witnora paths, 128 KiB per file and 256 KiB total. Duplicate paths and Witnora-key-shaped content are rejected.
• CI keys are created with only run/event/evidence scopes. A failed GitHub secret write revokes the newly created key.
• Webhooks use exact-byte HMAC verification and delivery-ID replay protection.
• Every operation stores actor, repository, request digest metadata, result, error and timestamps.

Acceptance checklist

1. Install on one private canary repository only.
2. Confirm a non-owner cannot obtain an install URL or authorize writes.
3. Add and remove repository access; verify webhook reconciliation.
4. Configure CI and confirm no secret value appears in Witnora logs or audit.
5. Dispatch the allowlisted workflow twice with separate idempotency keys.
6. Replay a webhook delivery ID and confirm it is ignored.
7. Uninstall the App and confirm the installation becomes revoked.
8. Run tenant-isolation tests before making the App public.

The customer-owned fallback remains:

npx witnora@latest setup apply --plan witnora-setup-plan.json --repo . --github-pr --configure-ci

This site is open source. Improve this page.