Skip to main content

Set Up GitHub Service Account

Create a dedicated GitHub service account to manage the Digital.ai Platform integration with your GitHub repositories. A service account prevents integration disruption when team members leave and maintains a clear audit trail.

Audience: GitHub Organization Administrators

A service account (also called a bot account) is a GitHub account not tied to an individual person. Using a service account for the CommitStream integration provides:

  • Security: Integration credentials separate from personal accounts
  • Continuity: Integration continues working when team members leave
  • Audit Trail: Automated actions clearly separated from user actions
  • Access Control: Precise control over integration permissions
  • Compliance: Meets organizational security requirements
important

Use a shared distribution list email (e.g., github-service@yourcompany.com) rather than a personal email address. This ensures token access, notifications, and account recovery are managed by the team, not an individual.

Prerequisites​

  • GitHub organization administrator privileges
  • Ability to add users to your GitHub organization
  • A shared distribution list or group email for the service account

Create GitHub Service Account​

Option A: Create a New Account​

  1. Sign out of your personal GitHub account (or use an incognito/private browser window)
  2. Navigate to https://github.com/signup
  3. Enter account details:

Email

  • Use a shared distribution list email
  • Example: github-service@yourcompany.com or digitalai-bot@yourcompany.com
  • Do not use a personal email

Password

  • Create a strong, unique password
  • Store it in your organization's password manager

Username

  • Choose a descriptive, non-personal name
  • Example: yourcompany-digitalai-bot or yourorg-scm-integration

Email preferences

  • Uncheck marketing emails (optional)
  1. Verify the email address using the link sent to the distribution list inbox
  2. Complete any additional GitHub verification steps
  3. Select Free account type (sufficient for CommitStream integration)

Option B: Use an Existing Service Account​

If your organization already has a GitHub service account:

  1. Verify you have credentials for the service account
  2. Confirm the account uses a distribution list email (not a personal email)
  3. Review the account's repository access permissions
  4. Proceed to the next section

Result: GitHub service account is created and ready to be added to your organization.

Add Service Account to Organization​

  1. Log in to GitHub with your admin account (not the service account)
  2. Navigate to https://github.com/orgs/YOUR_ORG_NAME/people (replace YOUR_ORG_NAME with your organization name)
  3. Click the People tab
  4. Click Invite member
  5. Enter the service account username or distribution list email
  6. Set role to Member (repository access is configured in the next step)
  7. Log in as the service account and accept the organization invitation from notifications or the distribution list inbox

Result: Service account is now a member of your GitHub organization.

Grant Repository Access​

note

Option B is simpler but provides broader access. Use Option A for tighter security control.

Grant the service account access to only the repositories needed for CommitStream integration.

  1. In your organization, navigate to Settings → Member privileges
  2. Click People in the left sidebar
  3. Locate the service account
  4. Click the gear icon (⚙️) next to the service account → Manage access
  5. Click Add repositories
  6. Select each repository that needs CommitStream integration
  7. Set permission level to Read (minimum required for reading commit information)
  8. Click Add to repository or Save

Option B: Organization-Wide Access​

Grant the service account read access to all repositories in the organization.

  1. Navigate to organization Settings → Member privileges
  2. Set base repository permission to Read for all members

Result: Service account can access the necessary repositories to read commit data.

Generate GitHub API Token​

Create a GitHub Personal Access Token (PAT) from the service account for Digital.ai Platform integration.

GitHub API Token Permissions​

Your GitHub API Token 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 API Token:

  • Use read-only permissions whenever possible.
  • Create tokens from the service account (not personal accounts).
  • 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.

Create the Token​

  1. Log in to GitHub using the service account credentials.
  2. Navigate to Settings → Developer settings → Personal access tokens → Tokens (classic).
  3. Click Generate new token → Generate new token (classic).
  4. Enter a descriptive note (e.g., Digital.ai Platform CommitStream Integration).
  5. Set expiration (recommend 90 days or longer for production use).
  6. Select the appropriate scopes based on your repository types (see permissions above).
  7. Click Generate token.
  8. Immediately copy the token - you won't be able to see it again.
  9. Store the token securely in your organization's password manager or secrets vault.
tip

For detailed instructions on creating GitHub Personal Access Tokens, see GitHub's official documentation: Managing your personal access tokens.

Result: GitHub API Token is generated and ready to use in Digital.ai Platform configuration.

Enable Two-Factor Authentication​

Enable 2FA on the service account following GitHub's recommended approach for shared service accounts.

GitHub provides specific guidance for managing 2FA on bot and service accounts. See Managing bots and service accounts with two-factor authentication for complete details.

Configure 2FA​

  1. Ensure all team members who need access are members of the distribution list email set up earlier
  2. Log in to GitHub with the service account
  3. Click your profile picture → Settings → Password and authentication
  4. Click Enable two-factor authentication
  5. Choose Authenticator app
  6. During setup, note the setup key (TOTP secret) displayed below the QR code
  7. Store the TOTP secret in your organization's shared password manager or secrets vault
  8. Download recovery codes and store them in the same shared vault
important

Store the TOTP secret (not just the password) in your shared password manager. Any team member can use this secret to generate valid login codes with any TOTP-compatible authenticator tool.

Result: Service account is secured with two-factor authentication that the team can manage.

Next Steps​

After setting up the GitHub service account:

  1. Configure Digital.ai Platform Integration - Connect Digital.ai Platform to GitHub using the service account and API token you created
Last updated on