GitHub

GitHub serves two roles in GridWork HQ: authentication (via OAuth) and repository management (via personal access token). This is a required integration.

What It Does

• Authentication — GitHub OAuth is the only login method. The ALLOWED_GITHUB_ID env var restricts access to your account.
• Repository tracking — the dashboard displays commit activity, deployment status, and repo health for your tracked repositories.
• Pipeline operations — the build pipeline creates repos, pushes code, and manages client sites through the GitHub API.

Setup

1. Create a GitHub OAuth App

1. Go to github.com/settings/applications/new
2. Fill in:
   • Application name: GridWork HQ
   • Homepage URL: http://localhost:3000 (or your production URL)
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
3. Click Register application
4. Copy the Client ID and generate a Client Secret

2. Create a Personal Access Token

1. Go to github.com/settings/tokens
2. Select scopes: repo, read:org
3. Generate and copy the token

3. Find Your GitHub User ID

Visit https://api.github.com/users/YOUR_USERNAME and copy the id field.

4. Configure Environment Variables

# In gridwork-hq/.env.local
GITHUB_ID=your-oauth-client-id
GITHUB_SECRET=your-oauth-client-secret
GITHUB_TOKEN=ghp_your-personal-access-token
GITHUB_ORG=your-org-or-username
ALLOWED_GITHUB_ID=12345678
TRACKED_REPOS=repo1,repo2,repo3

Environment Variables

Updating Callback URLs

If you move from local development to production:

1. Go to your GitHub OAuth App settings
2. Update the Homepage URL to your production URL
3. Update the Authorization callback URL to https://your-hq-url/api/auth/callback/github

The callback URL must match exactly, including the protocol and path.

Without This Integration

Without GitHub credentials, you cannot log in to the dashboard at all. GitHub OAuth is the sole authentication method.