GitHub Integration

Connect your GitHub issues to OKR objectives, key results, and team workflows

GitHub Integration Overview

The GitHub integration allows you to connect your GitHub issues directly to your OKR workflow in OKR Studio. Link issues to objectives and key results for comprehensive progress tracking and team alignment.

What You Can Connect

  • • OKR Objectives
  • • Key Results
  • • Team planning initiatives
  • • Development tasks

Key Benefits

  • • Track development progress
  • • Sync issue status updates
  • • Connect code to OKR goals
  • • Improve development visibility
Prerequisites

Before You Begin

  • • You need admin access to your GitHub repository or organization
  • • Your GitHub repository must be accessible (public or private with permissions)
  • • You'll need to create a GitHub Personal Access Token or GitHub App
  • • Ensure your OKR Studio plan supports integrations
Step 1: Create GitHub Personal Access Token

Generate Personal Access Token

  1. 1

    Go to GitHub Settings

    Navigate to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

  2. 2

    Generate New Token

    Click "Generate new token (classic)" and provide a descriptive note (e.g., "OKR Studio Integration")

  3. 3

    Select Required Scopes

    Enable the following scope:

    • • repo - Full repository access (required for issue management)
  4. 4

    Copy the Token

    Save this token securely - you'll need it for the OKR Studio configuration

Token Format

Your GitHub Personal Access Token should look like:

ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Configure OKR Studio
  1. 1

    Navigate to Integrations

    Go to Settings → Integrations in your OKR Studio workspace

  2. 2

    Enable GitHub Integration

    Click on the GitHub tab and toggle "Enable GitHub Integration" to ON

  3. 3

    Enter Personal Access Token

    Paste your GitHub Personal Access Token in the "Personal Access Token" field

  4. 4

    Test Connection

    Click "Test Connection" to verify your configuration and load available repositories

  5. 5

    Select Default Repository

    Choose a default repository from the dropdown for creating new issues

  6. 6

    Optional: Set Up Webhooks

    For automatic status updates when issues or pull requests are closed, expand the "Webhook Configuration" section and follow the step-by-step guide to add a webhook to each GitHub repository you want to track.

  7. 7

    Save Configuration

    Click "Save Settings" to activate the integration

Configuration Fields

Personal Access Token: Your GitHub token (ghp_xxx...)

Default Repository: Chosen from your accessible repositories

Webhook Configuration: Generate a secret and add webhooks to your repositories for automatic status updates

Using the GitHub Integration

Linking GitHub Issues

Once configured, you can link GitHub issues to various items in OKR Studio:

OKR Objectives

Link development tasks to objectives for better tracking and alignment.

Key Results

Connect feature development to key results and track progress automatically.

Team Initiatives

Link technical research and prototyping issues to team projects.

Planning Cycles

Connect development work to planning cycles and sprints.

How to Link Issues

  1. 1. Open the item you want to link (objective, key result, etc.)
  2. 2. Look for the "Linked Issues" or "GitHub Issues" section
  3. 3. Click "Link GitHub Issue" or the "+" button
  4. 4. Search for or enter the GitHub issue number (e.g., #123)
  5. 5. Select the issue and click "Link"

Status Synchronization

The integration automatically syncs issue status updates between GitHub and OKR Studio:

Open
In Progress
In Review
Closed
Troubleshooting

Common Issues

Authentication Failed

  • • Verify your GitHub URL is correct
  • • Check that your Personal Access Token hasn't expired
  • • Ensure your token has the required scopes
  • • Verify your username is correct

Issues Not Syncing

  • • Check the integration status in Settings → Integrations
  • • Verify the linked issue exists and is accessible
  • • Review sync logs for error messages
  • • Try unlinking and re-linking the issue

Permission Errors

  • • Ensure your token has "repo" scope for private repositories
  • • Check that you have access to the specified repository
  • • Verify your GitHub App has the correct permissions
  • • Contact your repository administrator if needed

Rate Limiting

  • • GitHub API has rate limits (5,000 requests/hour for authenticated users)
  • • Large repositories may hit rate limits during initial sync
  • • Consider using a GitHub App for higher rate limits
  • • Sync may be temporarily paused if limits are exceeded

Need Help?

If you're still experiencing issues, please contact our support team with:

  • • Your GitHub setup type (Personal Access Token or GitHub App)
  • • Error messages from the integration logs
  • • Screenshots of your configuration
  • • The specific repository you're trying to connect