Provider setup

Connect Entire

Use Entire as the checkout source for a GitHub repository, or register an Entire-native repository with its own identity, encrypted access token, and authenticated event relay.

Choose the connection model

The models share runner and workflow behavior but differ in source identity, events, status publishing, and credential ownership.

Model	Source identity and events	Checkout
GitHub + Entire mirror	GitHub owns repository identity, webhooks, pull requests, and Check Runs.	`entire://<cluster>/gh/<owner>/<repo>`
Entire-native	Entire ULID plus Runnable’s authenticated relay. Run status remains authoritative in Runnable.	`entire://<cluster>/et/<project>/<repo>`

Use an Entire mirror for GitHub checkout

The repository remains GitHub-backed. Only the source transport used by jobs changes.

1
Connect GitHub first
Install the Runnable GitHub App and let repository discovery complete.
2
Open checkout settings
On the repository page, select Entire mirror.
3
Provide the mirror URL
Use the exact entire://cluster/gh/owner/repository coordinates. Runnable rejects a mirror whose owner/name does not match the GitHub repository.
4
Store ENTIRE_TOKEN
Create a repository-scoped secret named ENTIRE_TOKEN. It is decrypted only for the checkout helper and remains masked.
5
Run a checkout test
Dispatch a small workflow with actions/checkout before moving deployment workloads.

Register an Entire-native repository

Organization administrators provide the Entire identity, clone coordinates, token, and optionally the current workflow files.

Field	Requirement
`providerRepositoryId`	Optional 26-character Entire repository ULID; otherwise derived from validated coordinates when available.
`project / name`	1–100 characters each; neither may contain a slash.
`cloneUrl`	Validated `entire://cluster/et/project/repository` URL, up to 2,048 characters.
`token`	Entire access token, stored as an encrypted repository-scoped `ENTIRE_TOKEN`.
`defaultBranch`	Defaults to main.
`workflowFiles`	Up to 100 files matching `.runnable/workflows/.yml` or `.yaml`; each content value is at most 256 KB.

Capture the relay credential immediately

The create response returns the repository webhook URL and bearer credential once. Runnable persists only its SHA-256 hash, so the cleartext value cannot be recovered later.

Send provider events to the relay

Supported events are push, pull_request, release, and repository_dispatch. Delivery IDs are idempotent within one Entire repository.

authenticated Entire relay requestHTTP

POST /api/entire/webhooks/REPOSITORY_ID HTTP/1.1
Host: runnable.cloud
Authorization: Bearer ONE_TIME_RELAY_CREDENTIAL
Content-Type: application/json

{
  "event": "push",
  "deliveryId": "provider-unique-delivery-id",
  "sha": "0123456789abcdef",
  "ref": "refs/heads/main",
  "actor": "rodrigo",
  "changedFiles": ["src/index.ts"],
  "workflowFiles": [
    {
      "path": ".runnable/workflows/ci.yml",
      "content": "name: CI\non: [push]\njobs: ..."
    }
  ]
}

The first delivery must include every current workflow file unless onboarding already supplied one. Later deliveries may omit workflowFiles to reuse the latest snapshots. When files are present, omitted workflow paths are disabled, matching repository discovery semantics.

Portable expressions

Entire-native jobs still expose the Actions-compatible github.* expression context. github.repository_id contains the Entire ULID, and no GitHub token endpoint is available.

Rotate checkout and relay credentials

Treat checkout and event relay credentials as separate secrets with separate blast radii.

Credential	Rotate by	Effect
ENTIRE_TOKEN	Replace the repository-scoped secret with a newly issued Entire token.	Future checkouts use the new encrypted value. Revoke the old token at Entire after a successful test.
Relay bearer credential	Use the repository’s Rotate relay credential control.	A new cleartext credential is shown once and the previous credential is invalid immediately.

1
Issue and store the replacement
Create the new credential at its authority and save it to the consuming system before removing the old one.
2
Test one delivery or checkout
Use a unique relay delivery ID or a small checkout-only workflow and confirm success in Runnable.
3
Revoke the old source credential
Relay rotation is already invalidating. For Entire access tokens, revoke the previous token at Entire after verification.

Current Entire boundaries

Runnable documents this boundary explicitly so customers do not mistake a relay contract for upstream registration support.

Automatic enrollment is not currently available

Entire’s current CI webhook registration contract accepts only the Buildkite provider, and its repository API does not expose commit-check/status writes. Runnable therefore cannot safely auto-enroll itself or publish conclusions inside Entire today.

Runs, conclusions, approvals, logs, and artifacts for Entire-native repositories are authoritative in Runnable. Public GitHub actions can be downloaded anonymously, while private GitHub actions require a GitHub-backed repository.

NextRuns and operationsFollow provider events through dispatch, jobs, approvals, and conclusions.