GitHub Integration

GuideMode integrates with GitHub to provide comprehensive visibility into your development workflow. This integration enables organization sync, pull request tracking, issue management, and deployment analytics for DORA metrics.

What You Get

• Organization & Team Sync: Automatically sync your GitHub organization members and teams to GuideMode
• Pull Request Tracking: Link AI coding sessions to pull requests for end-to-end traceability
• Issue Tracking: Monitor issues and their lifecycle through your workflow
• Deployment Tracking: Capture deployment events for DORA metrics (lead time, deployment frequency)
• Label Mapping: Map your GitHub labels to GuideMode’s analytical categories

Prerequisites

Before setting up the GitHub integration, you’ll need:

• A GitHub account with admin access to your organization (for org sync)
• Access to create OAuth Apps and GitHub Apps in GitHub Developer Settings
• Admin permissions in your GuideMode tenant

Setup Overview

The GitHub integration uses two components:

1. GitHub OAuth App - For user authentication (logging in with GitHub)
2. GitHub App - For organization sync, webhooks, and repository access

Step 1: Create a GitHub OAuth App

The OAuth App handles user authentication when users log in with GitHub.

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click New OAuth App
3. Fill in the details:
   • Application name: GuideMode (or your preferred name)
   • Homepage URL: https://guidemode.dev (or your deployment URL)
   • Authorization callback URL: https://guidemode.dev/auth/github/callback
4. Click Register application
5. Copy the Client ID
6. Click Generate a new client secret and copy the secret

Step 2: Create a GitHub App

The GitHub App enables team sync, webhooks, and repository access.

1. Go to GitHub Settings > Developer settings > GitHub Apps
2. Click New GitHub App
3. Fill in the basic details:
   • GitHub App name: guidemode (must be unique across GitHub)
   • Homepage URL: https://guidemode.dev

Configure Webhook Settings

4. Enable webhooks and set:
   • Webhook URL: https://guidemode.dev/api/github/webhook
   • Webhook secret: Generate a secure random string and save it

Set Permissions

5. Configure Repository permissions:

   • Issues: Read-only
   • Pull requests: Read-only
   • Deployments: Read-only
   • Contents: Read-only (for repository metadata)

6. Configure Organization permissions:

   • Members: Read-only
   • Administration: Read-only (for team structure)

Subscribe to Events

7. Under Subscribe to events, enable:
   • Issues
   • Pull request
   • Pull request review
   • Deployment
   • Deployment status
   • Member
   • Membership
   • Team
   • Repository

Generate Private Key

8. Click Create GitHub App
9. On the app page, click Generate a private key
10. Download and securely store the .pem file
11. Copy the App ID from the app settings page

Step 3: Environment Configuration

Add these environment variables to your GuideMode deployment:

OAuth App Variables

GITHUB_CLIENT_ID=your_oauth_client_id
GITHUB_CLIENT_SECRET=your_oauth_client_secret

GitHub App Variables

GITHUB_APP_ID=123456
GITHUB_APP_NAME=guidemode
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...your private key contents...
-----END RSA PRIVATE KEY-----"
GITHUB_APP_WEBHOOK_SECRET=your_webhook_secret

For local development, add these to your .dev.vars file in the server app.

Step 4: Install the GitHub App

Once your GuideMode instance is configured:

1. Navigate to Settings > GitHub in GuideMode
2. Click Install GitHub App
3. Choose your organization or personal account
4. Select which repositories to grant access to:
   • All repositories: Recommended for full visibility
   • Selected repositories: For limited access
5. Click Install to complete

Organization Sync

After installing the GitHub App, you can sync your organization:

What Gets Synced

• Members: All organization members are created as users in GuideMode
• Teams: GitHub teams are mirrored to GuideMode teams
• Team memberships: Member roles (member/maintainer) are preserved
• Repository links: Team repositories are linked to GuideMode projects

Triggering a Sync

1. Go to Settings > GitHub
2. Click Sync Organization
3. Wait for the sync to complete (status shows progress)

Syncs run automatically when:

• A new member joins the organization
• Team memberships change
• Teams are created or modified

Pull Request Integration

When a pull request is opened in a repository where GuideMode has detected a coding session, the integration adds context to the PR:

This provides end-to-end traceability from AI session through to deployed code.

Requirements:

• Session data must be synced (at least Metrics Only mode)
• For full auditability, enable Full Transcript sync

Label Mapping

GuideMode maps GitHub labels to internal issue types for analytics. This enables consistent reporting across different projects that may use different labeling conventions.

Issue Types

GuideMode classifies issues into these categories:

Type	Description
feature	New functionality or enhancements
bug	Defects, fixes, regressions
chore	Maintenance, refactoring, tech debt
discovery	Research, spikes, investigations
incident	Production issues, outages, emergencies
other	Uncategorized issues

Default Label Heuristics

When no custom mappings are configured, GuideMode uses these heuristics (case-insensitive, partial matching):

Bug: Labels containing bug, defect, fix, regression

Feature: Labels containing feature, enhancement, improvement, story

Chore: Labels containing chore, refactor, tech-debt, maintenance, cleanup

Discovery: Labels containing spike, research, investigation, discovery, exploration

Incident: Labels containing incident, outage, critical, emergency, or matching p0, p1, sev0, sev1

Custom Label Mappings

You can configure custom mappings per project or globally for your tenant. Custom mappings take priority over default heuristics.

Priority Order:

1. Project-specific mappings (highest)
2. Global tenant mappings
3. Default heuristics (lowest)

To configure custom mappings, use the GuideMode API or contact support.

Webhook Events

The GitHub App receives real-time updates via webhooks:

Supported Events

Event	Actions	What’s Captured
issues	opened, edited, closed, reopened, labeled, unlabeled	Issue lifecycle and type changes
pull_request	opened, synchronize, reopened, closed, edited	PR lifecycle, additions/deletions
pull_request_review	submitted, edited, dismissed	Review feedback
deployment	created	Deployment events for DORA metrics
deployment_status	created	Success/failure status
member	added, removed	Organization membership
membership	added, removed	Team membership changes
team	created, deleted, edited	Team lifecycle
repository	created, deleted, archived	Repository changes
installation	created, deleted, suspended	App installation status

DORA Metrics

Deployment events power DORA metrics calculations:

• Deployment Frequency: How often you deploy to production
• Lead Time for Changes: Time from commit to production
• Change Failure Rate: Percentage of deployments causing issues
• Time to Restore: How quickly you recover from failures

Repository Configuration

Each project can be configured for what to sync:

Setting	Description
syncIssues	Enable/disable issue tracking
syncPullRequests	Enable/disable PR tracking
syncDeployments	Enable/disable deployment tracking

Configure these in the project settings within GuideMode.

Troubleshooting

OAuth Login Fails

• Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correct
• Check the callback URL matches exactly: {APP_URL}/auth/github/callback
• Ensure the OAuth App is not suspended

Webhooks Not Received

• Verify webhook URL is accessible from GitHub
• Check the webhook secret matches GITHUB_APP_WEBHOOK_SECRET
• Review webhook delivery history in GitHub App settings
• Ensure the app has the required event subscriptions

Sync Fails

• Verify the GitHub App is installed on the organization
• Check the private key is correctly formatted (PEM format with newlines)
• Ensure the app has Members: Read-only organization permission
• Review sync logs in GuideMode for specific errors

Missing Team Data

• Confirm the app has Administration: Read-only permission
• Trigger a manual sync from Settings
• Check that teams exist in the GitHub organization

Labels Not Mapping Correctly

• Review your custom mappings (project-specific take priority)
• Check that label names match (case-insensitive)
• Use default heuristics as a guide for naming labels