Catalio logo
Sign in

Integrations

GitHub Integration

Connect Catalio to GitHub to create seamless traceability between your requirements and your development workflow. Link requirements to issues, pull requests, and commits to maintain complete visibility from planning through deployment.

Overview

Why Integrate GitHub with Catalio?

The GitHub integration bridges the gap between product requirements and engineering implementation. By connecting Catalio’s requirement management with GitHub’s development workflow, teams gain:

Complete Traceability

  • Track which requirements are being worked on in real-time
  • See which pull requests implement specific requirements
  • Identify commits that address particular features or bugs
  • Trace code changes back to original business needs

Automated Workflow

  • Automatically update requirement status based on issue state
  • Link pull requests to requirements through commit messages
  • Sync issue descriptions and comments between platforms
  • Trigger notifications when code is merged

Enhanced Visibility

  • Provide stakeholders with development progress without GitHub access
  • Generate reports showing requirement implementation status
  • Identify requirements without associated issues or PRs
  • Monitor cycle time from requirement to deployment

Reduced Context Switching

  • View GitHub activity directly in Catalio
  • Create GitHub issues from requirements with one click
  • Access requirement details from GitHub issues
  • Maintain single source of truth for requirement definitions

Integration Capabilities

The Catalio-GitHub integration supports:

  • Bi-directional Issue Sync: Create issues from requirements and sync status updates
  • Pull Request Linking: Associate PRs with requirements for implementation tracking
  • Commit Traceability: Link commits to requirements through message conventions
  • Repository Connection: Connect multiple repositories to a single Catalio project
  • Webhook Automation: Real-time updates when issues, PRs, or commits change
  • GitHub Projects: Sync with GitHub Projects for unified board views
  • Enterprise Support: Full compatibility with GitHub Enterprise Server

Prerequisites

GitHub Account Requirements

GitHub Cloud (github.com)

  • Personal account with repository access, or
  • Organization membership with appropriate permissions
  • Minimum required permissions:
    • repo scope for private repositories
    • public_repo scope for public repositories only
    • read:org scope for organization information
    • write:discussion scope for issue comments

GitHub Enterprise Server

  • GitHub Enterprise Server 3.0 or later
  • Network connectivity between Catalio and your GitHub Enterprise instance
  • Admin approval for OAuth App or GitHub App installation
  • SSL certificate properly configured (self-signed certificates require additional setup)

Repository Access Levels

The integration requires different access levels depending on functionality:

Read-Only Integration (Minimum)

  • View issues, pull requests, and commits
  • Link existing issues to requirements
  • Display GitHub activity in Catalio
  • Required permission: read:repo

Standard Integration (Recommended)

  • All read-only capabilities
  • Create issues from requirements
  • Update issue status and labels
  • Post comments from Catalio
  • Required permissions: repo, write:discussion

Advanced Integration (Full Features)

  • All standard capabilities
  • Manage webhooks for real-time sync
  • Create and update GitHub Projects
  • Manage repository settings
  • Required permissions: repo, write:discussion, admin:repo_hook, write:org

Catalio Project Setup

Before connecting GitHub:

  1. Create a Catalio Project: Ensure you have a project where requirements are organized
  2. Define Requirements: Have at least some requirements defined to test the integration
  3. Configure Roles: Ensure team members have appropriate Catalio permissions
  4. Plan Repository Mapping: Decide which GitHub repositories map to which Catalio projects

Authentication

Catalio supports two authentication methods for GitHub integration: OAuth Apps and GitHub Apps. Understanding the differences helps you choose the right approach for your organization.

OAuth Apps vs GitHub Apps

OAuth Apps - User-Based Authentication

OAuth Apps authenticate as the user who installed the integration. This approach is simpler to set up but has limitations for team environments.

Pros:

  • Quick setup with minimal configuration
  • No approval required from GitHub organization admins
  • Works immediately for personal repositories
  • Familiar OAuth flow for users

Cons:

  • Permissions tied to installing user’s access
  • Integration stops working if user leaves organization
  • No fine-grained repository access control
  • Higher rate limits but shared across user’s apps
  • Actions appear as the installing user

Best For:

  • Personal projects and small teams
  • Quick proof-of-concept implementations
  • Organizations without strict security requirements
  • Temporary integrations or testing

GitHub Apps - Installation-Based Authentication

GitHub Apps authenticate as the application itself with fine-grained permissions. This is the recommended approach for production environments.

Pros:

  • Permissions independent of individual users
  • Survives user account changes and departures
  • Fine-grained repository access control
  • Higher dedicated rate limits (5,000 requests/hour)
  • Actions appear as the app (e.g., “catalio-bot”)
  • Supports organization-level installation
  • Better security through granular permissions

Cons:

  • Requires organization admin approval
  • More complex initial setup
  • Requires webhook configuration for notifications
  • Need to manage app installation lifecycle

Best For:

  • Production deployments
  • Organizations with multiple repositories
  • Teams with security and compliance requirements
  • Long-term integrations requiring reliability
  • Scenarios requiring high API rate limits

Setting Up OAuth App Authentication

Step 1: Register OAuth App in GitHub

  1. Navigate to GitHub Settings → Developer settings → OAuth Apps
  2. Click “New OAuth App”
  3. Configure the OAuth App:
    • Application name: “Catalio Integration - [Your Org]”
    • Homepage URL: https://your-catalio-instance.com
    • Authorization callback URL: https://your-catalio-instance.com/integrations/github/callback
    • Description: “Links Catalio requirements to GitHub issues and pull requests”
  4. Click “Register application”
  5. Note your Client ID (shown immediately)
  6. Click “Generate a new client secret”
  7. Copy and save the Client Secret immediately (shown only once)

Step 2: Configure OAuth in Catalio

  1. Log into Catalio as an administrator
  2. Navigate to Settings → Integrations → GitHub
  3. Select “OAuth App” as authentication method
  4. Enter your OAuth App credentials:
    • Client ID: The Client ID from GitHub
    • Client Secret: The Client Secret you generated
    • GitHub URL: https://github.com (or your GitHub Enterprise URL)
  5. Click “Save Configuration”

Step 3: Authorize the Integration

  1. In Catalio, navigate to Project Settings → Integrations
  2. Click “Connect GitHub”
  3. You’ll be redirected to GitHub’s authorization page
  4. Review the requested permissions
  5. Click “Authorize [Your OAuth App Name]”
  6. You’ll be redirected back to Catalio with active connection

Security Note: The OAuth token is stored encrypted in Catalio’s database. Revoke access anytime through GitHub Settings → Applications → Authorized OAuth Apps.

Setting Up GitHub App Authentication

Step 1: Create GitHub App

  1. Navigate to GitHub Settings → Developer settings → GitHub Apps
  2. Click “New GitHub App”
  3. Configure the GitHub App:
    • GitHub App name: “Catalio Integration”
    • Homepage URL: https://your-catalio-instance.com
    • Webhook URL: https://your-catalio-instance.com/webhooks/github
    • Webhook secret: Generate a strong random secret (save for later)
    • Permissions (Repository permissions):
      • Issues: Read & write
      • Pull requests: Read & write
      • Contents: Read-only
      • Metadata: Read-only
      • Webhooks: Read & write
      • Projects: Read & write (if using GitHub Projects)
    • Subscribe to events:
      • Issues
      • Issue comments
      • Pull requests
      • Pull request reviews
      • Pushes
  4. Click “Create GitHub App”
  5. Note your App ID
  6. Generate and download a private key (save securely)

Step 2: Install GitHub App

For Organization Repositories:

  1. Navigate to your GitHub App settings
  2. Click “Install App” in the left sidebar
  3. Select your organization
  4. Choose repository access:
    • All repositories: Grant access to all current and future repos
    • Only select repositories: Choose specific repos for integration
  5. Click “Install”
  6. Note the Installation ID from the URL (e.g., /installations/12345678)

For Personal Repositories:

  1. Follow the same process but select your personal account
  2. Installation ID appears in the URL after installation

Step 3: Configure GitHub App in Catalio

  1. Log into Catalio as an administrator
  2. Navigate to Settings → Integrations → GitHub
  3. Select “GitHub App” as authentication method
  4. Enter your GitHub App credentials:
    • App ID: The App ID from GitHub
    • Installation ID: The Installation ID from the installation URL
    • Private Key: Paste the entire private key file contents
    • Webhook Secret: The webhook secret you generated
    • GitHub URL: https://github.com (or your GitHub Enterprise URL)
  5. Click “Save Configuration”
  6. Click “Test Connection” to verify authentication

Step 4: Verify Webhook Configuration

  1. Navigate to your GitHub App settings → Advanced
  2. View “Recent Deliveries” to see webhook activity
  3. In Catalio, navigate to Settings → Integrations → GitHub → Webhook Status
  4. Verify that webhooks are being received and processed
  5. Test by creating an issue in a connected repository and confirming it appears in Catalio

Security Best Practices:

  • Store private keys in secure secrets management (e.g., HashiCorp Vault)
  • Rotate webhook secrets periodically
  • Monitor “Recent Deliveries” for unauthorized webhook attempts
  • Use separate GitHub Apps for development and production environments
  • Regularly audit GitHub App installations and repository access

GitHub Enterprise Configuration

Additional Setup for GitHub Enterprise Server

  1. Verify network connectivity: Ensure Catalio can reach your GitHub Enterprise instance
  2. SSL certificate handling:
    • Valid certificates: No additional configuration needed
    • Self-signed certificates: Add certificate to Catalio’s trusted store
  3. Update GitHub URL field to your Enterprise URL: https://github.your-company.com
  4. Configure firewall rules to allow webhook callbacks from GitHub Enterprise to Catalio
  5. Consider using a dedicated service account for GitHub App installations

Enterprise-Specific Considerations:

  • GitHub Enterprise Server 3.0+ required for full GitHub Apps support
  • OAuth Apps work with all Enterprise versions
  • Rate limits may differ from GitHub Cloud (verify with your admin)
  • SAML/SSO configuration does not affect API authentication
  • IP allowlists must include Catalio’s IP addresses for webhooks

Repository Connection

Once authentication is configured, connect specific GitHub repositories to Catalio projects to enable requirement tracking.

Connecting Repositories to Projects

Step 1: Navigate to Project Settings

  1. Open your Catalio project
  2. Click Settings → Integrations → GitHub
  3. Click “Connect Repository”

Step 2: Select Repository

For OAuth App Authentication:

  • View list of repositories you have access to
  • Use search to filter repositories
  • Select the repository to connect
  • Click “Connect”

For GitHub App Authentication:

  • View repositories where the GitHub App is installed
  • If repository isn’t listed, you need to add it to the GitHub App installation
  • Select the repository from the list
  • Click “Connect”

Step 3: Configure Repository Settings

After connecting a repository, configure integration behavior:

Default Branch

  • Select the primary branch for issue creation (usually main or develop)
  • Pull requests targeting this branch will be prioritized in reports
  • Default: main

Issue Label Sync

  • Enable automatic label synchronization between Catalio and GitHub
  • Map Catalio requirement categories to GitHub labels
  • Example: “Feature” → enhancement, “Bug” → bug

Auto-Link Settings

  • Auto-create issues: Automatically create GitHub issues when requirements are approved
  • Auto-link PRs: Automatically link PRs to requirements based on commit messages
  • Status sync: Sync requirement status based on issue state
    • Issue opened → Requirement status “In Development”
    • PR merged → Requirement status “Implemented”
    • Issue closed → Requirement status “Complete”

Branch Strategy

  • Configure branch naming conventions for automatic linking
  • Example: feature/REQ-123-user-authentication automatically links to requirement REQ-123
  • Supported patterns: feature/, bugfix/, hotfix/, enhancement/

Multiple Repository Configuration

For projects spanning multiple repositories:

  1. Connect each repository following the same process
  2. Designate a primary repository for default issue creation
  3. Configure repository-specific settings:
    • Frontend repository: UI-focused requirements default here
    • Backend repository: API and business logic requirements default here
    • Infrastructure repository: DevOps and deployment requirements default here

Repository Selection Rules:

  • Requirements tagged “frontend” → Frontend repository
  • Requirements tagged “api” → Backend repository
  • Requirements without tags → Primary repository
  • Manual override available per requirement

Disconnecting Repositories

To remove a repository connection:

  1. Navigate to Project Settings → Integrations → GitHub
  2. Find the connected repository in the list
  3. Click “Disconnect”
  4. Confirm the action

What Happens on Disconnect:

  • Existing issue links remain but are marked “disconnected”
  • Webhooks are automatically removed from GitHub
  • No new synchronization occurs
  • Historical data remains in Catalio for reporting

Data Retention:

  • Linked issue IDs and URLs are preserved
  • Issue descriptions and comments remain cached
  • Pull request references remain visible
  • Commit links remain functional (pointing to GitHub)

Issue Synchronization

The core feature of the GitHub integration is bi-directional synchronization between Catalio requirements and GitHub issues.

Creating Issues from Requirements

Manual Issue Creation

  1. Navigate to a requirement in Catalio
  2. Click “Link to GitHub” → “Create New Issue”
  3. Configure the issue:
    • Repository: Select target repository (defaults to primary)
    • Title: Pre-filled from requirement title (editable)
    • Description: Generated from requirement details
    • Labels: Auto-mapped from requirement categories
    • Assignees: Select from repository collaborators
    • Milestone: Choose existing milestone or create new
    • Projects: Add to GitHub Project boards
  4. Click “Create Issue”
  5. Issue is created in GitHub and automatically linked to the requirement

Automatic Issue Creation

Configure automatic issue creation for specific requirement workflows:

  1. Navigate to Project Settings → Integrations → GitHub → Automation
  2. Enable “Auto-create issues”
  3. Configure trigger conditions:
    • When requirement is approved: Create issue when requirement moves to “Approved” status
    • When requirement is prioritized: Create issue when priority is set to “High” or “Critical”
    • When requirement is assigned: Create issue when developer is assigned
  4. Configure issue templates:
    • Use GitHub issue templates for consistent formatting
    • Map requirement fields to issue template fields
    • Include requirement link in issue description

Issue Description Template

When creating issues from requirements, Catalio generates descriptions with:

Requirement Details

Catalio ID: REQ-123 Category: Feature Enhancement Priority: High Link: https://catalio.example.com/requirements/REQ-123

Description

[Requirement description from Catalio]

Acceptance Criteria

  • [Criterion 1]
  • [Criterion 2]
  • [Criterion 3]

Additional Context

[Use cases, personas, and assumptions from Catalio]

This issue was created from Catalio requirement REQ-123

Linking Existing Issues

Manual Linking

  1. Navigate to a requirement in Catalio
  2. Click “Link to GitHub” → “Link Existing Issue”
  3. Search for issues:
    • Search by issue number: #123
    • Search by issue title: User authentication flow
    • Filter by labels, milestones, or assignees
  4. Select the issue to link
  5. Click “Link Issue”

Automatic Linking via Labels

Configure a special GitHub label to enable automatic linking:

  1. Create a label in GitHub: catalio:REQ-{id} (e.g., catalio:REQ-123)
  2. When you add this label to any issue, it automatically links to the corresponding requirement
  3. Removal of the label removes the link

Bulk Linking

For existing projects with many issues:

  1. Navigate to Project Settings → Integrations → GitHub → Bulk Actions
  2. Click “Bulk Link Issues”
  3. Select a repository
  4. Catalio analyzes issue titles and descriptions for requirement references
  5. Review suggested links
  6. Approve or reject each suggestion
  7. Click “Apply Links”

Status Synchronization

Configure how issue status changes affect requirement status:

GitHub Issue State → Catalio Requirement Status

Default Mappings:

  • Issue opened → Requirement “In Development”
  • Issue closed (PR merged) → Requirement “Implemented”
  • Issue closed (not planned) → Requirement “Rejected”
  • Issue reopened → Requirement “In Development”

Custom Mappings:

  1. Navigate to Project Settings → Integrations → GitHub → Status Mapping
  2. Configure state transitions:
    • Issue has linked PR → Requirement “In Review”
    • Issue labeled “blocked” → Requirement “Blocked”
    • Issue in milestone “Sprint 5” → Requirement “Planned for Sprint 5”
  3. Enable or disable automatic status updates per mapping

Catalio Requirement Status → GitHub Issue

When requirement status changes in Catalio, the integration can:

  • Add labels to reflect new status (e.g., add status:in-progress)
  • Update issue milestone when requirement sprint changes
  • Post comment noting the status change
  • Close issue when requirement is marked “Complete”

Conflict Resolution

When status changes occur in both systems simultaneously:

  • Priority: GitHub changes take precedence (closer to implementation)
  • Notification: Catalio notifies requirement owner of conflicts
  • Manual Override: Requirement owner can force Catalio status to GitHub

Comment Synchronization

GitHub Comments → Catalio

All comments posted on linked issues appear in Catalio:

  • Threaded conversations: Maintain reply structure
  • Code references: Preserve syntax highlighting
  • @mentions: Convert GitHub usernames to Catalio users
  • Attachments: Images and files display inline

Catalio Comments → GitHub

Comments posted in Catalio on requirements with linked issues:

  • Can be configured to post to GitHub automatically
  • Include author attribution: “Comment by @username in Catalio”
  • Preserve formatting and attachments
  • Link back to Catalio requirement

Privacy Controls

Configure which comments sync:

  1. Navigate to Project Settings → Integrations → GitHub → Comment Sync
  2. Choose sync direction:
    • GitHub → Catalio only: Import all GitHub discussion (default)
    • Bi-directional: Sync both directions
    • Catalio → GitHub only: Push Catalio discussion to GitHub
  3. Configure filters:
    • Exclude bot comments: Don’t sync automated bot posts
    • Exclude internal comments: Mark Catalio comments as internal-only
    • Sync only specific labels: Only sync comments on labeled issues

Label Management

Syncing Catalio Categories to GitHub Labels

Map requirement categories to GitHub labels:

  1. Navigate to Project Settings → Integrations → GitHub → Label Mapping
  2. Map categories:
    • Catalio “Feature” → GitHub enhancement
    • Catalio “Bug” → GitHub bug
    • Catalio “Technical Debt” → GitHub tech-debt
    • Catalio “Security” → GitHub security
  3. Configure auto-creation: Create GitHub labels if they don’t exist
  4. Configure sync direction: One-way or bi-directional

Custom Label Workflows

Use labels to trigger actions:

  • Priority Labels: Add priority:high when requirement priority changes
  • Sprint Labels: Add sprint-5 when requirement added to sprint
  • Team Labels: Add team:frontend based on requirement assignment
  • Status Labels: Add status:ready when requirement is ready for development

Pull Request Tracking

Link pull requests to requirements to track implementation progress and maintain complete traceability.

Automatic PR Linking

Commit Message Conventions

Catalio automatically links pull requests to requirements based on commit messages:

Supported Formats:

REQ-123: Implement user authentication flow

[REQ-123] Add OAuth provider configuration

Fixes REQ-123 - Authentication error handling

Implements requirement REQ-123

Closes REQ-123: Complete authentication feature

Keywords:

  • REQ-{id}: Basic reference
  • Fixes REQ-{id}: Marks requirement as fixed
  • Closes REQ-{id}: Marks requirement as complete
  • Implements REQ-{id}: Marks implementation complete
  • Refs REQ-{id}: Reference without status change
  • Relates to REQ-{id}: Loose association

Branch Name Conventions

Pull requests from branches following these patterns auto-link:

feature/REQ-123-user-authentication

bugfix/REQ-456-fix-login-issue

enhancement/REQ-789-improve-performance

hotfix/REQ-101-security-patch

Multiple Requirements

Link one PR to multiple requirements:

REQ-123, REQ-124: Implement authentication and authorization

Fixes REQ-456, Fixes REQ-457

Manual PR Linking

From Catalio

  1. Navigate to a requirement
  2. Click “Linked Pull Requests” → “Link Pull Request”
  3. Search for PRs:
    • Filter by repository
    • Filter by branch name
    • Filter by author
    • Filter by status (open, closed, merged)
  4. Select the PR to link
  5. Click “Link”

From GitHub

Add a comment to any PR with the requirement reference:

This PR implements REQ-123

Catalio’s webhook integration detects the reference and creates the link automatically.

PR Status Tracking

Visual Indicators in Catalio

When viewing a requirement with linked PRs:

  • PR Status: Open, Draft, Review Requested, Changes Requested, Approved, Merged
  • Review Status: Approved, Changes Requested, Commented, Pending
  • CI/CD Status: Checks passing, failing, or pending
  • Merge Status: Mergeable, conflicts, blocked
  • Timeline: PR opened date, last update, merged date

Status-Based Requirement Updates

Configure automatic requirement status updates based on PR activity:

  1. PR Opened: Requirement → “In Development”
  2. PR Review Requested: Requirement → “In Review”
  3. PR Changes Requested: Requirement → “Revisions Needed”
  4. PR Approved: Requirement → “Approved for Merge”
  5. PR Merged: Requirement → “Implemented”
  6. PR Closed (not merged): Requirement → “Development Paused”

Review Integration

Displaying Reviews in Catalio

Pull request reviews appear in the requirement timeline:

  • Review type: Approved, Changes Requested, Commented
  • Reviewer: GitHub username with link to profile
  • Review date: Timestamp
  • Review body: Full comment text
  • Code comments: Link to specific file/line in GitHub

Review Notifications

Notify requirement stakeholders of PR reviews:

  • On approval: Notify product owner that implementation is ready
  • On changes requested: Notify developer and requirement owner
  • On comments: Notify relevant team members
  • Configure notification rules in Project Settings → Notifications

Merge Activity Tracking

Merge Events

When a PR is merged, Catalio records:

  • Merge timestamp: When the PR was merged
  • Merged by: User who performed the merge
  • Target branch: Branch the PR was merged into
  • Merge method: Merge commit, squash, or rebase
  • Commit SHA: Reference to the merge commit

Deployment Tracking

If your GitHub Actions or CI/CD pipeline includes deployment information:

  • Catalio detects deployment webhooks
  • Associates deployments with requirements via merged PRs
  • Displays deployment status: “Deployed to Staging”, “Deployed to Production”
  • Links to deployment URLs for verification

Release Notes Generation

Use merged PRs to generate release notes:

  1. Navigate to Projects → Releases → New Release
  2. Select date range or milestone
  3. Catalio generates release notes from:
    • Requirements completed in the range
    • Associated PRs that were merged
    • Commit messages and PR descriptions
  4. Review and edit generated notes
  5. Publish to team or export to GitHub Releases

Commit Traceability

Track individual commits associated with requirements for granular development visibility.

Commit Message Parsing

Automatic Commit Linking

Catalio analyzes commit messages in linked repositories to associate commits with requirements:

Supported Commit Message Patterns:

git commit -m "REQ-123: Implement user authentication"

git commit -m "[REQ-123] Add login form validation"

git commit -m "Fixes REQ-123 - Resolve authentication error"

git commit -m "WIP REQ-123: Initial authentication implementation"

Conventional Commits Support

Catalio recognizes Conventional Commits format:

git commit -m "feat(auth): REQ-123 implement OAuth provider"

git commit -m "fix(auth): REQ-456 handle expired tokens"

git commit -m "docs(api): REQ-789 update authentication guide"

git commit -m "refactor(auth): REQ-101 extract token validation"

Multiple Requirements per Commit

Reference multiple requirements in a single commit:

git commit -m "REQ-123, REQ-124: Shared authentication utilities"

git commit -m "Fixes REQ-456, Refs REQ-457"

Commit Timeline

Viewing Commits in Catalio

For each requirement, view the commit timeline:

  1. Navigate to requirement details
  2. Click “Development Activity” → “Commits” tab
  3. View chronological list of commits:
    • Commit message: Full message text with links
    • Author: Developer with avatar and profile link
    • Timestamp: When the commit was made
    • Branch: Which branch contains the commit
    • Files changed: Count and breakdown by type
    • Additions/Deletions: Lines of code changed
    • Link to GitHub: View full commit diff

Commit Statistics

Aggregate statistics for requirement development:

  • Total commits: Number of commits referencing the requirement
  • Contributors: Developers who contributed
  • Files affected: Files modified across all commits
  • Lines changed: Total additions and deletions
  • Commit frequency: Timeline chart showing development activity
  • Avg commit size: Average lines changed per commit

Code Change Analysis

File Change Tracking

Track which files were modified for each requirement:

  • File path: Full path in repository
  • Change type: Added, modified, deleted, renamed
  • Change magnitude: Lines added/deleted
  • Primary language: File type (e.g., JavaScript, Python, CSS)
  • Link to file: View current state in GitHub

Language Breakdown

Analyze development work by programming language:

  • Lines by language: Total changes per language
  • Commits by language: Commits primarily affecting each language
  • Estimate effort: Rough development time based on changes
  • Technology stack: Technologies involved in implementation

Development Metrics

Cycle Time Analysis

Track time from requirement creation to implementation:

  1. Time to First Commit: Requirement created → First commit
  2. Development Duration: First commit → Last commit
  3. Review Time: Last commit → PR approval
  4. Time to Merge: PR opened → PR merged
  5. Total Cycle Time: Requirement created → PR merged

Developer Attribution

Track developer contributions to requirements:

  • Primary developer: Developer with most commits
  • Contributing developers: All developers with commits
  • Reviewer contributions: Developers who reviewed PRs
  • Commit distribution: % of commits by each developer

Commit Quality Indicators

Analyze commit patterns for insights:

  • Commit size: Categorize as small, medium, large, very large
  • Commit frequency: Daily activity patterns
  • Rework rate: Commits that modify recently changed lines
  • WIP commits: Commits marked as work-in-progress
  • Revert commits: Commits that undo previous work

GitHub Projects Integration

Synchronize Catalio requirements with GitHub Projects (formerly GitHub Projects Beta) for unified project management.

Connecting to GitHub Projects

Step 1: Authorize Projects Access

Ensure your GitHub App or OAuth App has the write:org and write:project permissions:

  1. Navigate to GitHub App settings → Permissions → Organization permissions
  2. Enable “Projects” with “Read & Write” access
  3. Save changes and re-authorize in Catalio if needed

Step 2: Link Catalio Project to GitHub Project

  1. Navigate to Project Settings → Integrations → GitHub → Projects
  2. Click “Link GitHub Project”
  3. Select repository or organization that owns the project
  4. Choose the GitHub Project from the list
  5. Click “Connect”

Step 3: Configure Field Mapping

Map Catalio fields to GitHub Project custom fields:

Standard Mappings:

  • Catalio “Status” → GitHub Project “Status” field
  • Catalio “Priority” → GitHub Project “Priority” field
  • Catalio “Assignee” → GitHub Project “Assignees” field
  • Catalio “Sprint” → GitHub Project “Iteration” field

Custom Field Mapping:

  • Create custom fields in GitHub Projects
  • Map to Catalio custom fields
  • Configure sync direction (one-way or bi-directional)

Synchronizing Project Boards

Adding Requirements to GitHub Projects

Automatic Addition:

  1. Enable “Auto-add to GitHub Project” in Project Settings
  2. When requirement has linked issue, it’s automatically added to GitHub Project
  3. Requirement appears as card in the configured status column

Manual Addition:

  1. Navigate to requirement in Catalio
  2. Click “Add to GitHub Project”
  3. Select which GitHub Project to add to
  4. Choose initial status column
  5. Click “Add”

Column Mapping

Map GitHub Project columns to Catalio requirement statuses:

  1. Navigate to Project Settings → Integrations → GitHub → Projects → Column Mapping
  2. Configure mappings:
    • GitHub “Backlog” → Catalio “Approved”
    • GitHub “Ready” → Catalio “Planned”
    • GitHub “In Progress” → Catalio “In Development”
    • GitHub “In Review” → Catalio “In Review”
    • GitHub “Done” → Catalio “Complete”
  3. Enable bi-directional sync

Status Sync Behavior:

  • When card moves between columns in GitHub, requirement status updates in Catalio
  • When requirement status changes in Catalio, card moves to mapped column in GitHub
  • Conflicts are resolved based on configured precedence (GitHub or Catalio)

GitHub Projects v2 Features

Custom Fields Support

GitHub Projects v2 introduces custom fields that can be synchronized:

Supported Field Types:

  • Text: Sync with Catalio text fields
  • Number: Sync with Catalio numeric fields
  • Date: Sync with Catalio date fields
  • Single Select: Sync with Catalio dropdown fields
  • Iteration: Sync with Catalio sprint fields

Configuration:

  1. Define custom fields in GitHub Project
  2. Map to corresponding Catalio fields
  3. Configure sync rules and precedence

Views and Filters

Create GitHub Project views based on Catalio data:

  • By Priority: Group cards by requirement priority
  • By Category: Group by requirement category
  • By Sprint: Group by Catalio sprint
  • By Owner: Group by requirement owner

Automation Rules

Leverage GitHub Projects automation with Catalio:

  • Auto-assign when card moves to “In Progress”
  • Set due date when card moves to “Scheduled”
  • Add label when moved to “Blocked”

Reporting and Insights

Catalio Reports with GitHub Project Data

Generate reports combining Catalio and GitHub Project information:

Velocity Reports:

  • Requirements completed per sprint
  • Story points delivered vs. planned
  • Burndown charts with GitHub issue completion

Workflow Reports:

  • Time spent in each GitHub Project column
  • Bottleneck identification (columns with long duration)
  • Flow efficiency metrics

Team Performance:

  • Developer workload across Catalio and GitHub
  • Cycle time by team member
  • Contribution distribution

Webhooks and Real-Time Sync

Configure webhooks for instant synchronization between GitHub and Catalio without manual polling.

Webhook Configuration

Automatic Webhook Setup (GitHub App)

When using GitHub App authentication, Catalio automatically configures webhooks:

  1. Webhooks are set up during repository connection
  2. Webhook URL: https://your-catalio-instance.com/webhooks/github
  3. Webhook secret is configured for authentication
  4. Events are automatically subscribed based on enabled features

Manual Webhook Setup (OAuth App)

For OAuth App authentication or custom webhook configuration:

  1. Navigate to GitHub repository → Settings → Webhooks
  2. Click “Add webhook”
  3. Configure webhook:
    • Payload URL: https://your-catalio-instance.com/webhooks/github
    • Content type: application/json
    • Secret: Generate and save in Catalio (Settings → Integrations → GitHub → Webhook Secret)
    • SSL verification: Enable (requires valid SSL certificate)
    • Events: Select individual events (see below)
    • Active: Enabled
  4. Click “Add webhook”
  5. Test delivery by clicking “Recent Deliveries” → “Redeliver”

Webhook Events

Required Webhook Events for Core Functionality:

Issues Events:

  • issues - Issue opened, edited, closed, reopened, assigned
  • issue_comment - Comments added, edited, deleted

Pull Request Events:

  • pull_request - PR opened, edited, closed, merged, synchronized
  • pull_request_review - Reviews submitted, edited, dismissed
  • pull_request_review_comment - Review comments added, edited

Commit Events:

  • push - Commits pushed to any branch
  • create - Branch or tag created
  • delete - Branch or tag deleted

Project Events (Optional):

  • project_card - Card moved between columns
  • project - Project created, edited, closed

Configuration:

  1. Enable/disable specific event handling in Catalio
  2. Navigate to Settings → Integrations → GitHub → Webhook Events
  3. Toggle events based on your needs:
    • ☑️ Issues (required for issue sync)
    • ☑️ Pull Requests (required for PR tracking)
    • ☑️ Commits (required for commit traceability)
    • ☐ Projects (optional for GitHub Projects sync)
    • ☐ Stars (optional for popularity tracking)

Webhook Security

Verifying Webhook Authenticity

Catalio validates all incoming webhooks using HMAC signatures:

  1. Signature Generation: GitHub generates HMAC-SHA256 signature using webhook secret
  2. Signature Transmission: Included in X-Hub-Signature-256 header
  3. Signature Verification: Catalio recomputes signature and compares
  4. Rejection: Invalid signatures are rejected with 401 Unauthorized

Security Best Practices:

  • Use strong webhook secrets: Generate cryptographically random secrets (32+ characters)
  • Rotate secrets periodically: Update webhook secrets every 90 days
  • Monitor failed deliveries: Alert on repeated webhook validation failures
  • Enable SSL verification: Never disable SSL verification in production
  • IP allowlist: Configure firewall to only accept webhooks from GitHub IP ranges
  • Audit webhook activity: Review webhook logs regularly for anomalies

Webhook Secret Rotation:

  1. Generate new webhook secret in password manager
  2. Add new secret to Catalio (Settings → Integrations → GitHub → Webhook Secret)
  3. Catalio validates both old and new secrets during transition period
  4. Update webhook secret in GitHub (Settings → Webhooks → Edit)
  5. After 24 hours, remove old secret from Catalio

Webhook Reliability

Delivery Guarantees

GitHub webhook delivery characteristics:

  • At-least-once delivery: Webhooks may be delivered multiple times
  • Idempotency: Catalio handles duplicate webhooks gracefully
  • Retry policy: GitHub retries failed deliveries for 48 hours
  • Timeout: Webhooks timeout after 10 seconds

Handling Webhook Failures

If Catalio is unavailable when webhook is delivered:

  1. GitHub retries with exponential backoff
  2. After 48 hours, GitHub stops retrying
  3. Manual sync available: Settings → Integrations → GitHub → “Sync Now”

Monitoring Webhook Health

In Catalio:

  1. Navigate to Settings → Integrations → GitHub → Webhook Status
  2. View metrics:
    • Total webhooks received: Count over time period
    • Failed webhooks: Webhooks that failed processing
    • Average processing time: Latency metrics
    • Recent activity: Last 100 webhook deliveries with status

In GitHub:

  1. Navigate to Repository → Settings → Webhooks
  2. Click on webhook URL
  3. View “Recent Deliveries” with response codes and payloads
  4. Redeliver failed webhooks manually

Real-Time Updates

Immediate Synchronization

With webhooks enabled, updates are near-instant:

Scenario 1: Issue Created in GitHub

  1. Developer creates issue in GitHub (0s)
  2. GitHub sends webhook to Catalio (~1s)
  3. Catalio receives and processes webhook (~2s)
  4. Requirement appears in Catalio with linked issue (~3s)
  5. Team members receive notification (~4s)

Scenario 2: PR Merged in GitHub

  1. PR merged in GitHub (0s)
  2. Webhook triggers to Catalio (~1s)
  3. Requirement status updated to “Implemented” (~2s)
  4. Stakeholders notified of completion (~3s)
  5. Project metrics updated (~4s)

Scenario 3: Requirement Updated in Catalio

  1. Requirement priority changed in Catalio (0s)
  2. Catalio API call updates GitHub issue label (~1s)
  3. GitHub webhook confirms label update (~2s)
  4. Catalio confirms bidirectional sync (~3s)

Live Updates in UI

Catalio uses Phoenix LiveView for real-time UI updates:

  • Requirement pages update automatically when linked issues change
  • No page refresh required
  • Visual indicators show recent updates
  • Optimistic UI updates for immediate feedback

Best Practices

Optimize your GitHub integration for maximum development workflow efficiency.

Development Workflow Optimization

1. Establish Requirement-First Development

Always start with requirements in Catalio before creating GitHub issues:

  1. Define requirement with clear acceptance criteria
  2. Review and approve requirement
  3. Create or link GitHub issue from requirement
  4. Begin development with requirement context

Benefits:

  • Ensures development aligns with business needs
  • Maintains traceability from concept to code
  • Provides stakeholders visibility without GitHub access
  • Enables accurate planning and estimation

2. Use Consistent Naming Conventions

Standardize branch and commit naming across the team:

Branch Naming:

feature/REQ-123-user-authentication

bugfix/REQ-456-fix-login-error

enhancement/REQ-789-improve-performance

Commit Messages:

git commit -m "REQ-123: Implement OAuth provider configuration"

git commit -m "REQ-123: Add token validation middleware"

git commit -m "REQ-123: Update authentication documentation"

PR Titles:

REQ-123: Implement user authentication with OAuth

Benefits:

  • Automatic linking without manual intervention
  • Clear context in git history
  • Easier code reviews with requirement reference
  • Simplified release notes generation

3. Configure Status Automation Thoughtfully

Balance automation with manual control:

Recommended Automations:

  • ✅ Auto-link PRs based on commit messages
  • ✅ Update requirement to “In Development” when issue opened
  • ✅ Update requirement to “Implemented” when PR merged
  • ✅ Create GitHub issue when requirement approved

Manual Control for:

  • ❌ Requirement approval (requires human judgment)
  • ❌ Requirement rejection (needs stakeholder input)
  • ❌ Priority changes (business decision)
  • ❌ Closing issues (may need verification)

4. Leverage GitHub Projects for Sprint Planning

Use GitHub Projects as sprint board with Catalio integration:

  1. Create GitHub Project for current sprint
  2. Link to Catalio project
  3. Add requirements to sprint in Catalio
  4. Automatically populate GitHub Project
  5. Team manages daily work in GitHub Project
  6. Status syncs back to Catalio for stakeholder visibility

5. Implement Code Review Gates

Require requirement validation in code reviews:

  • PR template includes requirement reference
  • Reviewers verify implementation matches acceptance criteria
  • Link to requirement included in PR description
  • Acceptance criteria checked off as PR review checklist

Team Collaboration Patterns

1. Role-Based Access

Define clear responsibilities:

Product Owners:

  • Create and approve requirements in Catalio
  • Review implementation against acceptance criteria
  • Monitor development progress via requirement status
  • Don’t need GitHub access for oversight

Developers:

  • Create GitHub issues from requirements
  • Use requirement ID in branches and commits
  • Link PRs to requirements
  • Update implementation notes in Catalio

Engineering Managers:

  • Monitor cycle time and velocity metrics
  • Review commit traceability
  • Identify blocked requirements
  • Access both Catalio and GitHub for full visibility

Stakeholders:

  • View requirements and status in Catalio
  • See linked GitHub activity without GitHub access
  • Comment on requirements, synced to GitHub issues
  • Receive notifications of implementation progress

2. Communication Channels

Establish when to use Catalio vs GitHub for discussions:

Use Catalio for:

  • Requirement clarification questions
  • Acceptance criteria negotiations
  • Business context and rationale
  • Stakeholder feedback and approvals
  • High-level implementation approach

Use GitHub for:

  • Technical implementation details
  • Code review discussions
  • Specific line-of-code feedback
  • CI/CD and deployment discussions
  • Developer-to-developer technical collaboration

Sync comments when discussions need visibility across tools.

3. Notification Strategy

Configure notifications to avoid overload:

Notify product owners:

  • When PR is opened for their requirement
  • When PR is merged (implementation complete)
  • When issue is blocked or has questions

Notify developers:

  • When requirement is approved and ready
  • When acceptance criteria are updated
  • When requirement priority changes

Notify stakeholders:

  • When requirement status reaches “Implemented”
  • When requirement is deployed to production
  • Weekly summary of completed requirements

Data Hygiene

1. Regular Sync Audits

Periodically review integration health:

  • Check for orphaned links (linked issues that were deleted)
  • Identify requirements without linked issues
  • Find closed issues with requirements still “In Development”
  • Review webhook delivery failures

Audit Schedule:

  • Daily: Webhook health check
  • Weekly: Orphaned link cleanup
  • Monthly: Comprehensive sync audit
  • Quarterly: Process and automation review

2. Archive Completed Work

Maintain performance as project grows:

  • Archive requirements completed more than 90 days ago
  • Retain links but stop active synchronization
  • Keep historical data for reporting
  • Reduce active webhook processing load

3. Manage Repository Connections

As repositories are deprecated:

  • Disconnect from Catalio
  • Document why disconnection occurred
  • Archive linked requirements appropriately
  • Update team on new repository connections

Security and Compliance

1. Access Control

Ensure proper permissions across systems:

  • Use GitHub App (not OAuth) for production
  • Grant minimum required repository permissions
  • Audit GitHub App installations quarterly
  • Review and revoke unnecessary personal access tokens

2. Sensitive Information

Prevent accidental exposure:

  • Mark sensitive requirements as “internal-only” (don’t sync to GitHub)
  • Review issue descriptions before auto-creation for confidential details
  • Configure comment sync to exclude internal discussions
  • Use private repositories for proprietary projects

3. Audit Trails

Maintain complete traceability:

  • Enable Catalio audit logging for integration actions
  • Review GitHub webhook logs regularly
  • Monitor for unauthorized repository connections
  • Track who links/unlinks issues and requirements

4. Data Retention

Comply with organizational policies:

  • Configure retention period for cached GitHub data
  • Regularly clean up disconnected repository data
  • Export requirement-to-code traceability before archival
  • Document retention policy in integration settings

Performance Optimization

1. Webhook Processing

Optimize for high-traffic repositories:

  • Configure webhook event filtering (only subscribe to needed events)
  • Implement rate limiting for webhook processing
  • Queue webhook processing for large payload batches
  • Monitor webhook processing latency

2. API Rate Limits

Stay within GitHub API limits:

  • Use GitHub App authentication (higher limits: 5,000/hour)
  • Cache GitHub data to reduce API calls
  • Batch API requests when possible
  • Monitor rate limit status in Catalio dashboard

3. Large Repository Handling

For repositories with thousands of issues:

  • Enable selective issue sync (filter by label or milestone)
  • Use incremental sync instead of full refresh
  • Configure longer cache TTLs
  • Consider separate GitHub App installations per repository group

Troubleshooting

Common Issues and Resolutions:

Issue: Webhooks Not Received

  • Symptom: Updates in GitHub don’t appear in Catalio
  • Check: GitHub webhook delivery logs for failed requests
  • Verify: Webhook URL is correct and Catalio is accessible
  • Solution: Redeliver webhook manually, check firewall rules

Issue: Automatic Linking Not Working

  • Symptom: Commits with REQ-ID don’t link to requirements
  • Check: Commit message format matches supported patterns
  • Verify: Repository is connected in Catalio
  • Solution: Review and update commit message conventions

Issue: Status Not Syncing

  • Symptom: Issue closed but requirement still “In Development”
  • Check: Status mapping configuration
  • Verify: Bi-directional sync is enabled
  • Solution: Manually trigger sync or update status mapping rules

Issue: Permission Errors

  • Symptom: “Forbidden” errors when creating issues
  • Check: GitHub App or OAuth token permissions
  • Verify: Token hasn’t expired or been revoked
  • Solution: Re-authorize integration with correct permissions

Issue: Duplicate Issues Created

  • Symptom: Multiple GitHub issues for same requirement
  • Check: Auto-create rules triggering multiple times
  • Verify: Webhook idempotency handling
  • Solution: Delete duplicate issues, configure proper automation rules

Conclusion

The GitHub integration transforms Catalio into a complete requirement-to-code traceability platform. By connecting your requirements directly to GitHub’s development workflow, you gain:

  • Complete Visibility: From initial requirement through to deployed code
  • Automated Workflows: Reduce manual status updates and linking
  • Enhanced Collaboration: Bridge communication between product and engineering
  • Data-Driven Insights: Understand cycle times, bottlenecks, and delivery metrics
  • Stakeholder Confidence: Provide real-time progress without granting GitHub access

Next Steps:

  1. Configure Authentication: Choose OAuth App or GitHub App based on your needs
  2. Connect Repositories: Link your primary development repositories
  3. Establish Conventions: Define branch naming and commit message patterns
  4. Configure Automation: Set up status sync and automatic issue creation
  5. Train Your Team: Ensure everyone understands the integration workflow
  6. Monitor and Optimize: Review metrics and adjust automation rules

For additional support, see:

Need Help?

Last Updated: January 6, 2025 Applies to: Catalio v1.0+, GitHub Cloud and Enterprise Server 3.0+
Next
Building Custom Integrations