Skip to main content

Configure Digital.ai Platform Integration

Set up GitHub as your Source Control Management (SCM) system in Digital.ai Platform and generate the authentication tokens required for CommitStream integration with Digital.ai Agility.

Overview​

This topic covers two essential steps for configuring Digital.ai Platform:

  1. Configure GitHub SCM Integration - Connect Digital.ai Platform to GitHub repositories
  2. Generate Platform Personal Access Token - Create authentication token for webhook security

Both steps are required for complete CommitStream functionality.

Prerequisites​

Digital.ai Platform:

  • Administrator privileges in Digital.ai Platform
  • Active Platform account and license

GitHub:

  • GitHub account with access to your organization's repositories
  • Ability to create GitHub Personal Access Tokens
  • Repository admin access

Part 1: Configure GitHub SCM Integration​

Step 1: Access Source Integrations​

  1. Log in to Digital.ai Platform
  2. Navigate to Source Integrations
  3. You'll see the Source Integrations page displaying all existing integrations
  4. Click the Add Instance button (top right corner) to create a new GitHub integration

Access Source Integrations

Step 2: Select GitHub as Source Integration​

After clicking Add Instance, you'll see the "Select a source to set up" page displaying various source control integrations as cards/tiles.

  1. Type github in the search bar at the top of the page
  2. The page will filter to show only GitHub-related integrations
  3. You'll see GitHub and GitHub Enterprise Server cards
  4. Locate the GitHub card (use "GitHub Enterprise Server" if you have a self-hosted installation)
  5. Click the Add integration button on the appropriate GitHub card to proceed

Select GitHub

Step 3: Enter Integration Details​

After clicking Add integration, the setup wizard begins with the Integration Details page:

  1. Name (required): Enter a descriptive name for this GitHub integration instance

    • Example: My_GitHub_SCM or GitHub-Main-Repos
    • This name will help you identify this integration in Digital.ai Platform
    • Can only contain alphanumeric characters, dots (.), dashes (-), and underscores (_)
    • This name will be visible in Digital.ai Agility when configuring repositories

  2. Description (optional): Add a description explaining the purpose of this integration

    • Example: GitHub integration for Agility CommitStream

  3. Click Continue to proceed to the connection configuration

Note: You'll see "Pending configuration" status until the setup is complete. The wizard shows two tabs: "Integration Details" (current) and "Connection Details" (next).

Enter Integration Details

Step 4: Configure Connection Details​

After clicking Continue from the Integration Details page, you'll see the Connection Details tab:

  1. URL (required): Enter the GitHub API base URL

    • For GitHub.com: https://api.github.com
    • For GitHub Enterprise Server: https://your-github-server.com/api/v3
    • The field shows "GitHub API Base URL" as a helper text

  2. Owner (required): Enter the GitHub owner

    • Format: organization/user
    • Example: digital-ai or my-github-username
    • Helper text shows: "GitHub Owner (Organization / User)"

  3. API Token (required): Paste the GitHub Personal Access Token with read-only permissions

    • The token will be masked (shown as dots) for security
    • Required permissions: repo:status, public_repo, or Contents: Read-only
    • Used only for retrieving commit details when webhook payloads exceed GitHub's 25 MB size cap

Configure Connection Details

note

The existence of this integration configuration serves as a marker that identifies this GitHub repository as connected to Digital.ai Platform. The integration itself enables commit tracking for Digital.ai Agility work items. Each SCM system has its own webhook payload structure and size cap - the API token is used as a fallback to retrieve commit details when payloads are capped.

Step 5: Test and Save Connection​

  1. Test the connection: Click Save and test connection to verify your credentials

    • Digital.ai Platform will validate the URL, owner, and token
    • Wait for confirmation that the connection is successful
    • If the test fails, review the troubleshooting section below

  2. Save your configuration:

    • Click Save and Continue to complete the GitHub integration setup
    • Or click Previous if you need to go back and modify the integration name
    • Click Cancel to abort the setup

Result: Your GitHub integration is now configured in Digital.ai Platform and ready to use with CommitStream.

Verify Integration Status​

After saving:

  1. The integration should appear in your Source Integrations list
  2. Status should show as "Active" or "Connected"
  3. The integration name will be available for selection in Digital.ai Agility CommitStream configuration

GitHub Personal Access Token Permissions​

Your GitHub PAT should have the following minimum permissions:

For public repositories:

  • public_repo - Access public repositories

For private repositories:

  • repo - Full control of private repositories (or more granularly:)
    • repo:status - Access commit status
    • repo_deployment - Access deployment status
    • public_repo - Access public repositories

Best practices for GitHub PAT:

  • Use read-only permissions whenever possible
  • Create a dedicated service account for integrations
  • Set appropriate token expiration dates (90 days or longer for production)
  • Document which tokens are used for which integrations
  • Store tokens securely in a password manager or secrets vault

Part 2: Generate Platform Personal Access Token​

Platform Personal Access Tokens (PATs) are used to authenticate webhook requests from GitHub to Digital.ai Platform.

Step 6: Access Personal Access Tokens​

  1. Stay logged in to Digital.ai Platform
  2. Navigate to the Digital.ai Platform overview page
  3. Click on your user profile icon (showing your initials) in the top-right corner
  4. A dropdown menu will appear with the following options:
    • View profile
    • Access tokens
    • Sign out
  5. Click on Access tokens to proceed to the token generation page

Access Personal Access Tokens

Step 7: Create New Token​

You'll see the Personal access tokens page with:

  • Generate new tokens section at the top
  • Tokens in use table showing any existing tokens

  1. In the Token name field, enter a descriptive name for your token

    • Example: token-for-commit-stream-webhook
    • Use a name that clearly identifies its purpose and integration
    • Recommended format: commitstream-[environment]-[date]

  2. Select the Expiration period from the dropdown

    • Options: 30 days, 60 days, 90 days, Never
    • For production integrations, consider using Never or 90 days
    • For testing, shorter periods (30-60 days) are recommended
    • Balance security requirements with operational convenience

  3. Click the Generate button

Create New Token

Step 8: Copy and Store Token​

  1. The token will be generated and displayed immediately
important

Make sure to copy your personal access token now. You won't be able to see it again!

  1. Click the Copy token button to copy the token to your clipboard
  2. Immediately paste the token in a secure location:
    • Secure password manager
    • Secrets management system
    • Encrypted documentation
    • You will need this token when configuring webhooks in GitHub

Copy and Store Token

Result: The new token will appear in the Tokens in use table with:

  • Token name
  • Creation date and time
  • Expiration date (or "Never")
  • Delete action
warning

Once you navigate away from this page, you cannot view the token value again. If you lose it, you must delete and regenerate a new token.

Token Security Best Practices​

Storage and Handling:

  • ✓ Copy and store the token immediately after generation
  • ✓ Keep tokens in a secure password manager or secrets vault
  • ✓ Never commit tokens to source code repositories
  • ✓ Never share tokens via email or messaging platforms
  • ✓ Limit access to tokens to authorized personnel only

Token Management:

  • ✓ Use descriptive names to identify token purposes
  • ✓ Set appropriate expiration dates based on security policies
  • ✓ Delete unused or expired tokens regularly
  • ✓ Rotate tokens periodically for enhanced security (quarterly recommended)
  • ✓ Document which services use which tokens

Access Control:

  • ✓ Create separate tokens for different integrations
  • ✓ Use service accounts for production integrations
  • ✓ Audit token usage regularly
  • ✓ Monitor for unauthorized access or suspicious activity

Manage Existing Tokens​

In the Tokens in use table, you can:

  • View all active tokens by name and creation date
  • Check expiration dates to plan token rotation
  • Delete tokens using the trash icon in the Actions column
  • Monitor token status and identify unused tokens

Note: Once a token is generated, you cannot view its value again. If you lose a token, you must delete it and generate a new one.

Token Expiration Management​

Before Token Expires​

  1. Note the expiration date when creating the token
  2. Set a calendar reminder to rotate the token 1-2 weeks before expiration
  3. Plan for token rotation during a maintenance window to minimize disruption
  4. Prepare communication to affected teams

When Token Expires or Needs Rotation​

  1. Generate a new token with a similar name (add version or date if needed)
  2. Update all services using the old token:
    • Update webhook URLs in all GitHub repositories
    • Test each webhook after updating
  3. Verify integration functionality with the new token
  4. Delete the expired token from the tokens list
  5. Document the token rotation in your change log

For Production Integrations​

Consider using tokens with longer expiration periods or "Never" to avoid service interruptions:

  • Advantage: No unexpected authentication failures
  • Trade-off: Requires manual rotation for security compliance
  • Best practice: Implement regular token rotation schedule (e.g., quarterly or annually)
  • Monitoring: Set up alerts for tokens nearing expiration

Use Cases for Platform PAT​

Platform Personal Access Tokens are used for:

  1. Webhook Authentication: Authenticate webhook requests from GitHub to Digital.ai Platform (primary use for CommitStream)
  2. API Access: Programmatic access to Digital.ai Platform APIs
  3. Integration Services: Service-to-service authentication for third-party tools
  4. Automation: CI/CD pipelines and automated workflows
  5. Custom Applications: Applications built on Digital.ai Platform APIs

Troubleshooting​

GitHub Integration Connection Test Fails​

Problem: Unable to connect to GitHub API

Solutions:

  • Verify the GitHub URL is correct (use https://api.github.com for GitHub.com)
  • For GitHub Enterprise, verify your server URL format
  • Check network connectivity and firewall rules
  • Ensure Digital.ai Platform can reach GitHub's servers
  • Review proxy settings if applicable

GitHub Authentication Errors​

Problem: Invalid or expired GitHub token error

Solutions:

  • Verify the GitHub PAT is correct (no extra spaces or characters)
  • Check that the token hasn't expired in GitHub
  • Ensure the token has the required repository permissions
  • Regenerate the token if necessary
  • Test the token with GitHub API directly (using curl or Postman)

GitHub Owner Not Found​

Problem: Cannot find specified organization or user

Solutions:

  • Verify the owner name is spelled correctly (case-sensitive)
  • Ensure the token has access to the specified owner's repositories
  • Check that the organization/user exists in GitHub
  • For private organizations, verify token permissions include private repository access

Platform Token Not Working​

Problem: Platform PAT authentication fails after generation

Solutions:

  • Verify you copied the complete token value (no truncation)
  • Check for extra spaces or characters when pasting
  • Ensure the token hasn't expired
  • Confirm the token is active in the Tokens in use table
  • Test the token with a simple webhook delivery

Lost Platform Token Value​

Problem: Need to view Platform PAT value again

Solution:

  • Token values cannot be retrieved after generation
  • Delete the old token in Digital.ai Platform
  • Generate a new token
  • Update all webhook URLs in GitHub repositories with the new token
  • Test webhook deliveries after updating

Platform Token Expired​

Problem: Webhook authentication fails with 401 error

Solutions:

  • Check token expiration date in Digital.ai Platform
  • Generate a new token before the old one expires
  • Update all webhook URLs with new token immediately
  • Test webhook deliveries after rotation
  • Delete the expired token

Verification Checklist​

Before proceeding to the next configuration step, verify:

  • ✅ GitHub integration appears in Digital.ai Platform Source Integrations list
  • ✅ GitHub integration status shows as "Active" or "Connected"
  • ✅ GitHub integration name is descriptive and meaningful
  • ✅ Platform Personal Access Token is generated and copied
  • ✅ Platform PAT is stored securely and accessible for next steps
  • ✅ Platform PAT expiration date is documented
  • ✅ Integration details are documented for team reference

Next Steps​

After completing Digital.ai Platform configuration:

  1. Configure Digital.ai Agility: Configure Digital.ai Agility for CommitStream

    • Enable CommitStream in backend configuration
    • Add repository connections in Agility UI
    • Generate webhook URLs

  2. Configure Webhooks: Configure Webhooks and Verify Integration

    • Set up webhooks in GitHub repositories
    • Use Platform PAT for webhook authentication
    • Test the complete integration

  3. Optional TeamRoom Setup: Configure TeamRoom CommitStream Panel

    • Customize CommitStream display per TeamRoom
    • Configure repository filtering
Last updated on