Learn how to link GitHub to Azure Boards

Learn how to link GitHub to Azure Boards

Azure Boards allows seamless integration with GitHub to track work items alongside commits, pull requests, and issues. This integration provides traceability between development tasks and the work being done in GitHub, making it easier for teams to manage and monitor their workflows.

Use GitHub to Track Work in Azure Boards

Azure Boards and GitHub integration enables teams to:

1. Track GitHub Pull Requests and Commits:

   • Automatically link commits and pull requests to work items in Azure Boards.

   • Maintain a traceable connection between code changes and tasks.

2. Sync GitHub Issues with Azure Boards Work Items: Convert GitHub issues into Azure Boards work items for better planning and tracking.

3. Collaborate Seamlessly: Combine GitHub’s code hosting capabilities with Azure Boards’ task management features.

Azure Boards App for GitHub

The Azure Boards App is the official GitHub app to enable this integration. It connects Azure Boards to your GitHub repositories, allowing you to link work items directly to GitHub activity.

Key Features:

1. Track GitHub commits, pull requests, and issues in Azure Boards.

2. Automatically update work item states based on GitHub actions (e.g., PR merged).

3. Add work item references in commit messages or PR descriptions.

Installing the Azure Boards App:

1. Navigate to GitHub Marketplace: Open the in the GitHub Marketplace.

2. Install the App:

   • Select the GitHub repositories you want to link with Azure Boards.

   • Grant permissions for the app to access repository data.

3. Configure in Azure Boards:

   • Open your Azure DevOps project.

   • Navigate to Project Settings > GitHub Connections.

   • Authenticate and link the GitHub app to Azure Boards.

Authenticating to GitHub

To enable the Azure Boards and GitHub integration, you need to authenticate with GitHub.

1. Personal Access Token (PAT):

   • Generate a PAT from your GitHub account with the required scopes (e.g., repo, read:user).

   • Use this PAT to authenticate when setting up the connection in Azure Boards.

2. OAuth Authentication:

   • Sign in to GitHub via Azure Boards using OAuth.

   • Grant Azure Boards access to your GitHub account and repositories.

Supported Integration Scenarios

Azure Boards supports integration with GitHub in two main scenarios:

1. From GitHub to Azure Boards

Use Case:

Developers working in GitHub need to reference or track tasks in Azure Boards.

Key Actions:

1. Add work item IDs (e.g., AB#123) in commit messages or PR descriptions.

2. GitHub activity (e.g., a merged PR) updates linked work items in Azure Boards automatically.

Example Workflow:

1. A developer pushes code with the commit message:

xxxxxxxxxx
1
1
Fixes AB#123: Updated database schema

2. Azure Boards recognizes AB#123 and links the commit to the corresponding work item.

3. The work item is updated with the commit details and PR status.

2. From Azure Boards to GitHub

Use Case:

Project managers and product owners in Azure Boards want visibility into development progress in GitHub.

Key Actions:

• Link Azure Boards work items to GitHub issues or pull requests.

• View GitHub activity directly in Azure Boards.

Example Workflow:

• A work item is linked to a GitHub issue.

• The issue’s status in GitHub automatically updates the work item in Azure Boards.

Steps to Link GitHub to Azure Boards

1. Set Up GitHub Integration in Azure Boards:

   • Navigate to Project Settings > GitHub Connections.

   • Click New Connection and authenticate with GitHub.

   • Select the repositories to connect to Azure Boards.

2. Configure Linking Rules: Enable automatic linking by including work item IDs (e.g., AB#123) in GitHub activity (commit messages, PR descriptions, or issue comments).

3. Sync GitHub Issues with Azure Boards (Optional): Use the Azure Boards-GitHub Issues synchronization tool to map GitHub issues to Azure Boards work items.

Best Practices for Using the Integration

1. Use Consistent Work Item References: Include AB#<work item ID> in commit messages or PR descriptions for automatic linking.

2. Automate Workflows: Set up automation rules in Azure Boards to move work items to "In Progress" or "Done" based on GitHub activity.

3. Leverage Dashboards: Use Azure DevOps dashboards to monitor progress and GitHub activity in one place.

4. Train Your Team: Educate developers on how to reference work items in commits and PRs to ensure smooth integration.

Benefits of Integration

1. Traceability: Connect code changes and GitHub activity to Azure Boards work items for full visibility.

2. Productivity: Eliminate manual updates by syncing work items and GitHub activity automatically.

3. Collaboration: Enhance coordination between project managers and developers working in separate tools.

Summary

This integration brings the best of Azure Boards' planning capabilities and GitHub's development platform into a single, cohesive workflow.