Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/cloudflare-os/llms.txt

Use this file to discover all available pages before exploring further.

The GitHub Gatekeeper connects Cloudflare OS to GitHub via OAuth, enabling agents and Gadgets to read repositories, browse issues, review pull requests, and act on your behalf — all within the narrow access scope you define. It also powers “Continue with GitHub” sign-in when enabled, using the minimal scopes required to read your verified email without granting full repository access at login time.

​
Capabilities

The GitHub Gatekeeper serves two distinct roles depending on how a user interacts with it.
When github is included in the deployment’s AUTH_GATEKEEPERS allowlist, a “Continue with GitHub” button appears on the login page.
  • Scopes requested: read:user user:email
  • Purpose: reads the account’s primary verified email to establish the user’s identity
  • Grant lifetime: transient — the token is discarded immediately after the email is read
No repository access is granted at sign-in time. The minimal scope ensures users are not prompted to approve broad permissions just to log in.

​
Resource Types

ResourceURL patternWhat agents can do
Repositoryhttps://github.com/:owner/:repoRead code, list branches, read file contents
Issuehttps://github.com/:owner/:repo/issues/:numberRead, comment, update labels
Pull Requesthttps://github.com/:owner/:repo/pull/:numberRead diff, comments, review status

​
Prerequisites

Use a GitHub OAuth App, not a GitHub App. Only OAuth Apps honor the scope parameter, which is what makes the minimal-on-login / full-on-connect behavior work. A GitHub App (client ID starting with Iv…) ignores scope entirely and will grant whatever permissions it was configured with to every user authorization — including during sign-in.
You will need:
  • A GitHub account with access to Developer Settings
  • The PUBLIC_BASE_URL of your Cloudflare OS deployment (e.g., https://os.example.com or http://localhost:8787 for local dev)

​
Setup

1

Create a GitHub OAuth App

  1. Go to GitHub Settings → Developer settings → OAuth Apps — choose OAuth Apps, not “GitHub Apps”.
  2. Click New OAuth App.
  3. Fill in the application details:
    • Application name: anything descriptive (e.g., “My Company OS”)
    • Homepage URL: your PUBLIC_BASE_URL
    • Authorization callback URL: ${PUBLIC_BASE_URL}/gatekeeper/github/oauth
    For local development, use http://localhost:8787/gatekeeper/github/oauth.
  4. Click Register application.
2

Generate a client secret

On the app’s settings page after registration:
  1. Click Generate a new client secret.
  2. Copy both the Client ID and the generated Client secret — you will need both in the next step.
3

Configure credentials

Create a .env file in the gatekeeper package directory:
packages/gatekeeper-github/.env
CLIENT_ID=your-client-id-here
CLIENT_SECRET=your-client-secret-here
The .env file is gitignored and should never be committed to source control.
4

Enable GitHub sign-in (optional)

To show “Continue with GitHub” on the login page, add github to the AUTH_GATEKEEPERS allowlist in your root .dev.vars (local) or deployment environment:
.dev.vars
AUTH_GATEKEEPERS=cloudflare,google,github
The order of values controls the order of the login buttons. No additional GitHub configuration is needed — the user:email scope is automatically requested for OAuth Apps.
5

Verify the setup

  1. Start the application in dev mode (pnpm dev-server + pnpm dev-client).
  2. Create or open a Gadget and navigate to the Connections tab.
  3. Click + New Connection and choose a GitHub resource type.
  4. If prompted, connect a GitHub account — you will be redirected to GitHub’s authorization page.
  5. After granting access, the tab closes and you are back in the Gadget.
  6. Use the picker to choose the repository, issue, or pull request to connect.

​
What Agents Can Do

Once a GitHub resource is introduced to an agent or Gadget, the agent can:
  • Read repository contents — browse files, read source code, check recent commits
  • List and read issues — search open issues, read issue bodies and comments
  • List and read pull requests — read diffs, review comments, check CI status
  • Create issues — draft a new issue with a title and body (queued for approval)
  • Comment on issues and PRs — post a comment on behalf of the connected user (queued for approval)
All write actions — creating issues, posting comments — go through the approval queue before reaching GitHub. The agent continues working on subsequent steps while the action waits for your review.

​
Using a GitHub App Instead

If you must use a GitHub App (client ID starting with Iv…), be aware of the following limitations:
  • GitHub Apps ignore the scope parameter. Permissions are fixed in the App’s configuration and apply to every user authorization, so sign-in cannot be restricted to minimal scopes.
  • To read the user’s email for sign-in, you must grant the App the Email addresses account permission: App Settings → Permissions & events → Account permissions → Email addresses → Read-only → save. Existing users must re-authorize to approve the added permission.
  • Without the Email addresses permission, the email lookup fails with Resource not accessible by integration and sign-in is rejected.
For these reasons, a GitHub OAuth App is strongly recommended.

​
Troubleshooting

You are using a GitHub App that lacks the Email addresses account permission. Switch to an OAuth App (recommended) or grant the App the Email addresses permission and ask existing users to re-authorize.
The callback URL in your OAuth App settings does not match what the application is sending. Verify it is set to exactly http://localhost:8787/gatekeeper/github/oauth — no trailing slash, http not https for local dev.
The authorization code has expired or was already used. Return to Cloudflare OS and try connecting again.
Your CLIENT_ID or CLIENT_SECRET is missing. Ensure the .env file exists at packages/gatekeeper-github/.env with both values, then restart the dev server.

Build docs developers (and LLMs) love

Get started for freeTalk to us