Provider setup

Connect GitHub

The Runnable GitHub App supplies trusted source, signed events, installation-scoped tokens, migration pull requests, and Check Runs. Repository selection remains under the GitHub installation owner’s control.

Required app permissions

Basic execution needs Contents: read and Checks: write. Migration and agent workflows need the additional installation grants listed below. Job tokens remain narrowed to each workflow even when the installation has broader authority.

Permission or event	Why Runnable needs it
Contents: read	Discover .runnable/workflows, resolve reusable workflows/actions, and clone the trusted revision.
Checks: write	Create and finalize provider-native status for workflow runs.
Contents: write	Create the migration branch and copy eligible workflow files. Required only for the PR assistant.
Pull requests: write	Open the reviewable migration pull request. Required only for the PR assistant.
Issues / Pull requests / Contents: write	Required when a declared workflow, such as Claude Code, comments or edits repository content.
Actions: read	Required by agent workflows that inspect CI runs or workflow results.
Workflow-requested scopes	Mint a job token no broader than the workflow/job permission map and the installation grant.
push, pull_request, merge_group, release, issues	Create provider-triggered runs and merge-queue checks from signed webhook deliveries.
issue_comment, pull_request_review, pull_request_review_comment	Run trusted default-branch agent workflows from comments and reviews.
repository_dispatch	Match typed external events to workflow trigger configuration.

least-privilege workflow token exampleYAML

permissions:
  contents: read
  checks: write

Permissions fail closed

If a workflow requests a scope the installation did not grant, validation or dispatch is blocked. Runnable never silently expands an installation token.

Install the app and select repositories

Organization owners and administrators connect installations from the dashboard.

1
Open repository onboarding
In Runnable, choose Connect GitHub. You are redirected to the GitHub App installation flow.
2
Choose the account
Select the GitHub user or organization that owns the repositories. GitHub may require an organization owner to approve the installation.
3
Limit repository access
Choose all repositories or selected repositories. Selected access is the safer default and can be changed later in GitHub App settings.
4
Return to Runnable
Runnable links the installation to the active organization and starts bounded-concurrency repository discovery.

One provider installation, one Runnable organization

An installation already linked to another Runnable organization is not silently transferred. This prevents credentials and repository events from crossing tenants.

Repository and workflow discovery

Linking the installation snapshots default-branch workflow files without creating synthetic runs, so schedules and manual dispatch are available immediately.

Repositories retain GitHub as their source identity even when Entire is selected as checkout.
Workflow files are discovered from .runnable/workflows/*.yml and *.yaml.
Every source revision produces immutable workflow definitions and diagnostics.
Removed workflow paths are disabled; historic runs keep their original snapshot.

If you change repository access in GitHub, return to the repositories page and allow discovery to reconcile the visible selection. A repository removed from the installation cannot receive new events or tokens.

Migrate GitHub Actions workflows

The migration assistant scans .github/workflows on the default branch, resolves reusable workflow and action metadata, and classifies every candidate.

1
Scan
Run the compatibility scan from the repository page. No branch or pull request is created.
2
Review diagnostics
Full candidates are eligible. Partial, Runtime-dependent, and Unsupported candidates remain excluded until their diagnostics are resolved.
3
Create a migration PR
Runnable copies only eligible files into .runnable/workflows and opens a reviewable pull request against the default branch.
4
Merge and run in parallel
After merge, discovery stores the new definitions while the original GitHub Actions files remain active. Compare representative runs before disabling or narrowing either provider.

Parallel pilot is deliberate

The PR never deletes .github/workflows. Duplicate checks are expected during the pilot; remove or narrow one copy only after Runnable is verified.

Choose GitHub or Entire checkout

A GitHub-backed repository can keep GitHub for events and checks while cloning job source from a validated Entire mirror.

Checkout provider	Configuration	Credential
GitHub	Default for GitHub-backed repositories.	Short-lived GitHub App token, refreshed per step and permission-narrowed.
Entire mirror	Validated `entire://<cluster>/gh/<owner>/<repository>` URL.	Repository-scoped encrypted `ENTIRE_TOKEN`.

Switching checkout is an administrator action and is audit logged. Select GitHub again to remove the mirror URL from the repository’s active checkout configuration.

Webhooks, checks, and credential safety

The public webhook is authenticated before durable processing starts. Provider delivery IDs make replay idempotent.

GitHub webhook signatures are verified before a delivery is appended.
Duplicate delivery IDs resume stalled durable processing without creating duplicate runs.
Runnable audits the GitHub App delivery log, requests failed or missing redeliveries, and reclaims accepted deliveries that did not finish processing.
Default-branch heads are checked independently every few minutes; an unseen commit creates one idempotent recovery push run per workflow and SHA.
Job tokens are repository-scoped, permission-narrowed, short-lived, and refreshed per step.
Fork pull requests receive no customer secrets; write repository permissions become read.
GitHub Checks reflect the authoritative Runnable conclusion for GitHub-backed runs.

Recovery still needs GitHub source APIs

Delivery recovery and ref reconciliation do not depend on GitHub Actions, but they do require the GitHub App and repository APIs to become reachable. A GitHub-wide API or Git outage can delay checkout and recovery until those services return.

A 2xx webhook is not proof of a run

If a repository is no longer selected, a workflow is invalid, filters do not match, or billing/environment admission blocks execution, a signed delivery can be accepted without producing a runnable job. Check repository diagnostics and the Runs page.

NextEntire setupUse an Entire mirror or register an Entire-native repository.