Skip to main content

CommitStream Integration Setup

CommitStream enables seamless integration between Digital.ai Agility and source control systems (GitHub, BitBucket, GitLab), providing real-time visibility of code commits directly within your work item tracking. When developers include work item references (e.g., S-01004) in their commit messages, those commits automatically appear in the corresponding Agility work items, providing complete development traceability.

Key Benefits:

  • Automatic tracking of GitHub commits within Agility work items
  • Complete development traceability and audit history
  • Real-time visibility of code changes linked to stories
  • Improved collaboration between development and planning teams
  • Support for GitHub, BitBucket, and GitLab repositories

Prerequisites​

Before beginning the CommitStream setup, ensure you have:

Digital.ai Platform:

  • Administrative access to Digital.ai Platform
  • Platform Identity Service integration enabled
  • Active Platform license

Digital.ai Agility:

  • Administrative access to Digital.ai Agility
  • Admin access to configuration files (for backend setup)
  • Active Agility license

Source Control:

  • Administrative access to your source control repository (GitHub/BitBucket/GitLab)
  • Ability to create Personal Access Tokens
  • Ability to configure webhooks
  • A test repository for demonstration and validation

Architecture Overview​

CommitStream creates a bridge between three systems:

  1. Digital.ai Platform - Manages source control integrations and webhook endpoints
  2. Source Control Repository - Sends commit data via webhooks (GitHub, BitBucket, or GitLab)
  3. Digital.ai Agility - Displays commit information within work items and team boards

Commitstream Architecture

How It Works:

  1. Developer commits code with work item reference in message:

    git commit -m "S-01004 Fix formatting in README.md"

  2. Repository sends webhook to Digital.ai Platform endpoint

  3. Digital.ai Platform processes commit data and extracts work item references

  4. Digital.ai Agility displays commit in the referenced work item

  5. Team members see complete development history in the story

Complete Setup Workflow​

The complete setup process follows these seven phases:

Phase 1: Configure Digital.ai Platform Integration​

Set up the GitHub SCM integration in Digital.ai Platform and generate authentication tokens.

Tasks:

  1. Configure GitHub SCM Integration in Digital.ai Platform

    • Add GitHub as an SCM system
    • Provide GitHub Personal Access Token
    • Configure repository access
    • Test the connection

  2. Generate Platform Personal Access Token

    • Create authentication token for webhook security
    • Store token securely for webhook configuration

See Configure Digital.ai Platform Integration for details.

Phase 2: Configure Digital.ai Agility Backend​

Enable CommitStream in Agility configuration files and connect to Digital.ai Platform.

Tasks:

  1. Enable CommitStream feature in configuration
  2. Configure Platform API endpoint
  3. Set up integration authentication
  4. Restart Agility services

See Configure Digital.ai Agility for CommitStream for details.

Who Performs: Operations/Admin team with server access

Phase 3: Setup Repository Connections in Agility UI​

Add GitHub repositories to Digital.ai Agility and generate webhook URLs.

Tasks:

  1. Enable CommitStream in Agility UI
  2. Add repository connections
  3. Configure SCM system settings
  4. Copy webhook URLs for each repository

See Configure Digital.ai Agility for CommitStream for details.

Who Performs: Agility administrators

Phase 4: Configure Repository Webhooks​

Set up webhooks in your GitHub repository to send commit events to Digital.ai Agility.

Tasks:

  1. Access webhook settings in GitHub repository
  2. Add webhook with Platform endpoint URL
  3. Attach Platform Personal Access Token for authentication
  4. Configure webhook triggers (push events)
  5. Verify webhook delivery

See Configure Webhooks and Verify Integration for details.

Who Performs: Repository administrators

Phase 5: Verify Integration​

Test the complete CommitStream integration end-to-end.

Tasks:

  1. Make a test commit with work item reference
  2. Verify webhook delivery in repository settings
  3. Confirm commit appears in Agility work item
  4. Validate commit data accuracy

Documentation: Configure Webhooks and Verify Integration

Phase 6: Configure TeamRoom Display (Optional)​

Customize CommitStream display at the TeamRoom level.

Tasks:

  1. Access TeamRoom settings
  2. Choose display mode (Global, Custom, or None)
  3. Configure custom repositories if needed

See Configure TeamRoom CommitStream Panel for details.

Who Performs: TeamRoom administrators

Phase 7: Team Rollout​

Train your team on using CommitStream and establish commit message standards.

Tasks:

  1. Train developers on commit message format
  2. Establish team conventions for work item references
  3. Share troubleshooting resources
  4. Monitor initial adoption and address issues

Commit Message Format​

To link commits to Agility work items, include the work item ID in your commit message:

Format: [WORKITEM-ID] Commit message description

Examples:

  • S-12345 Add new authentication feature
  • D-67890 Fix login validation bug
  • B-11111 Update documentation for API endpoints
  • T-54321 Update unit tests for user service

Supported Work Item ID Formats:

  • S-##### - Stories
  • D-##### - Defects
  • B-##### - Backlog items
  • T-##### - Tasks
  • TE-##### - Tests
  • RQ-##### - Requests

Multiple Work Item References:

You can reference multiple work items in a single commit:

git commit -m "S-12345 D-67890 Fix authentication and validation bugs"

Expected Sync Times​

  • Webhook Delivery: Immediate (< 30 seconds)
  • Platform Processing: 1-3 minutes
  • Agility UI Update: 2-5 minutes total

Note: Initial setup may take longer for first commit processing. Subsequent commits typically process faster.

Authentication & Security​

The integration uses two types of authentication tokens:

GitHub Personal Access Token (GitHub PAT)​

  • Purpose: Allows Digital.ai Platform to access GitHub APIs
  • Permissions: Read-only repository access (public and private repos)
  • Stored In: Digital.ai Platform integration configuration

Platform Personal Access Token (Platform PAT)​

  • Purpose: Authenticates webhook requests from GitHub to Digital.ai Platform
  • Permissions: Webhook write access
  • Stored In: GitHub webhook URL as query parameter

Security Best Practices:

  • Store tokens securely and never commit to source control
  • Grant minimal required permissions to tokens
  • Rotate tokens regularly per security policies (recommended: quarterly)
  • Monitor webhook activity and access logs
  • Use HTTPS for all webhook URLs
  • Enable SSL verification in webhook settings
  • Audit token usage and webhook configurations periodically

Troubleshooting Common Issues​

Webhook Delivery Failures​

Symptom: Webhook shows failed delivery or HTTP error codes in GitHub

Solutions:

  • Verify webhook URL is complete and includes valid Platform PAT
  • Check Platform PAT hasn't expired
  • Ensure Digital.ai Platform is accessible from repository hosting service
  • Verify SSL certificates if using HTTPS
  • Review GitHub webhook delivery details for specific error messages

CommitStream Data Not Appearing in Agility​

Symptom: Webhook delivers successfully but no data appears in Agility work items

Solutions:

  • Verify source integrations are active in Digital.ai Platform
  • Check Agility CommitStream configuration matches Platform integration names
  • Ensure work item references in commit messages use valid format (S-12345)
  • Verify work items exist and are not deleted
  • Wait additional time for processing (up to 10 minutes for initial setup)
  • Check Agility backend logs for processing errors

Authentication Issues​

Symptom: HTTP 401 or 403 errors in webhook delivery

Solutions:

  • Regenerate Digital.ai Platform PAT with appropriate permissions
  • Update webhook URL with new PAT value
  • Verify PAT hasn't expired (check expiration date)
  • Check Digital.ai Platform user permissions for webhook access
  • Ensure PAT is correctly appended to webhook URL as ?_auth_token=YOUR_TOKEN

Integration Connection Problems in Platform​

Symptom: Digital.ai Platform integrations show inactive or error status

Solutions:

  • Test connection credentials in Platform
  • Verify network connectivity from Platform to GitHub
  • Check GitHub service account permissions
  • Review Digital.ai Platform logs for detailed error messages
  • Verify GitHub PAT has required repository permissions
  • Ensure GitHub PAT hasn't expired

Commits Linked to Wrong Work Items​

Symptom: Commits appear in unexpected work items

Solutions:

  • Verify commit message format is correct (S-12345 not S12345)
  • Check for typos in work item IDs
  • Establish team conventions for work item references
  • Review commit history for incorrect references

Advanced Configuration​

Multiple Repository Setup​

To configure CommitStream for multiple repositories:

  • Same project: Use the same webhook URL for all repositories in the same project
  • Different projects: Create separate CommitStream configurations per project or scope
  • Repository filtering: Configure Digital.ai Platform integration with repository-specific settings
  • Bulk configuration: Use Platform APIs to configure multiple repositories programmatically

Custom Commit Message Parsing​

Configure custom patterns for linking commits to work items:

  • Default patterns: S-12345, D-67890 format
  • Custom regex patterns: Available in Digital.ai Platform configuration for specific parsing rules
  • Multiple references: Support for multiple work item references per commit message
  • Case sensitivity: Work item IDs are case-insensitive (S-12345 = s-12345)

TeamRoom-Specific Configuration​

  • Global Mode: Show all commits from configured repositories
  • Custom Mode: Show only commits from TeamRoom-specific repositories
  • None Mode: Hide CommitStream panel in specific TeamRooms
  • Per-Room Settings: Configure different display modes for different teams

Maintenance and Monitoring​

Regular Maintenance Tasks​

FrequencyTaskResponsible Team
MonthlyReview and rotate Personal Access TokensSecurity/Admin
QuarterlyVerify integration health and connectivityOperations
QuarterlyAudit webhook configurationsSecurity
As NeededUpdate webhook configurations for new repositoriesAdmin
As NeededRemove configurations for decommissioned repositoriesAdmin

Monitoring Points​

Digital.ai Platform Integration Status:

  • Check source integration health dashboard
  • Monitor connection status and error rates
  • Review integration logs for anomalies

Webhook Delivery Rates:

  • Monitor successful vs. failed deliveries in GitHub
  • Track delivery response times
  • Alert on persistent delivery failures

Data Processing Times:

  • Track commit-to-display latency
  • Identify processing bottlenecks
  • Monitor Platform API performance

User Adoption:

  • Monitor CommitStream data usage in Agility
  • Track percentage of commits with work item references
  • Gather user feedback on integration value

Health Check Procedures​

Weekly Health Check:

  1. Verify at least one recent commit appears in Agility
  2. Check webhook delivery success rate (target: >95%)
  3. Review integration status in Digital.ai Platform

Monthly Health Check:

  1. Test end-to-end integration with new commit
  2. Verify all active repositories are sending webhooks
  3. Review and address any error patterns
  4. Update documentation for any configuration changes

Next Steps​

Ready to begin the setup? Start with Phase 1:

  1. Configure Digital.ai Platform Integration - Set up GitHub SCM and generate authentication tokens
  2. Configure Digital.ai Agility for CommitStream - Enable CommitStream in Agility backend and UI
  3. Configure Webhooks and Verify Integration - Set up repository webhooks and test integration
  4. Configure TeamRoom CommitStream Panel - Customize TeamRoom display (Optional)

Support and Resources​

For issues or questions:

Last updated on