Connect source control

Admin guide

Greenlight delivers every change to every app through pull requests. The platform talks to your source-control system through the Greenlight GitHub App, which scopes Greenlight’s access to a specific GitHub organization and specific repositories.

GitHub Supported GitLab Coming soon Bitbucket Coming soon

GitLab and Bitbucket will follow the same App-based pattern; GitHub is the supported source-control provider today.

What the App does

The Greenlight GitHub App is responsible for:

• Creating repositories when an agent calls greenlight.registerApp.
• Opening pull requests on behalf of agents (the PR’s author is the bound user; the App is the source).
• Posting the policy-check status on every PR.
• Reading metadata Greenlight needs to display the app’s status and history in the dashboard.

The App does not have admin permissions on your GitHub organization, push to main, or modify branch-protection rules outside the repositories Greenlight created.

Install

1. Start from the dashboard. Navigate to Admin → Source control and click Install GitHub App. You’ll be redirected to GitHub’s App install flow.
2. Pick the target organization. Install the App on the GitHub organization that will host your Greenlight-managed repositories.
3. Choose repository scope. Greenlight needs to create repositories, so install with “All repositories” or with the + Create new repositories permission. Existing-repo adoption is a separate post-install workflow.
4. Confirm permissions. GitHub will list the permissions the App is asking for. They map to the responsibilities above; no admin or org-owner permissions are requested.
5. Verify in the dashboard. Back in Greenlight, the Source control page should show the App as installed with a green checkmark.

Branch protection

Greenlight creates new repositories with branch-protection rules pre-configured:

• main requires the greenlight/policy-check status to be green before merge.
• Force-push to main is disabled.
• Required reviewers is set per the org’s policy bundle (typically 1 reviewer + the policy check, or 0 reviewers + the policy check for low-risk app classes).

The rules are visible in GitHub’s branch-protection UI and editable there. Greenlight does not silently reset them; if you change a rule in GitHub, it stays.

Existing repositories

The default install path is for Greenlight to create new repositories for every app. Bringing an existing repository under Greenlight governance — repo adoption — is a more deliberate workflow, since the existing history needs to pass a one-time policy scan and the repo’s existing branch protection has to be reconciled. The flow is documented separately; ask in your install for the adoption playbook if you have an existing app to onboard.

What apps see in their repo

A Greenlight-managed repo has the same shape as any other repo, plus:

• A greenlight.yml at the root with app_id and required docs metadata (resources and env vars are managed via MCP, not the file).
• A pre-commit hook (optional) that runs the same scanners the policy check runs, so the agent gets fast feedback.
• A GitHub Actions workflow Greenlight installs and updates, which posts the policy-check status.

The app developer and the agent both treat the repo as a normal Git repo. The policy enforcement happens through PR statuses, not through hidden tooling.

Tip

GitLab and Bitbucket support are on the roadmap. The conceptual model (a per-SCM app, scoped to an organization, with a PR-only delivery path) is identical across providers.

Next

Source control & the policy check The concept page covering what the check evaluates.

Manage integrations GitHub also shows up as a service-account integration for app-time API calls.

greenlight.yml The per-app manifest format.