Integrating Azure DevOps with GitHub - Hybrid Model

Overview

Welcome to another part of my series 'GitHub Codespaces Pro Tips'. In the last part we spoke about what a Codespace is and how to get started with your first Dev container.

Since Codespaces is a service on GitHub, you might be wondering or thinking that the service is limited to GitHub users only. The fact is that Codespaces is a service that is linked to a Git repository hosted on GitHub, but that is not a limiting factor to be able to use this great service along with other great services such as Azure DevOps Boards and Azure DevOps Pipelines.

Azure DevOps allows you to closely integrate services such as Boards and Pipelines with your GitHub account/Org.

So today we will be talking a bit more about integration between GitHub and Azure DevOps and how their services can co-exist in a single environment.

I will be showing you how you can create a hybrid environment with GitHub and Azure DevOps, by linking your DevOps boards and pipelines to GitHub. Allowing you to use the best of both worlds where you can combine services and features of GitHub, such as Codespaces, Dependabot and baked in code scanning capabilities, along with existing Azure DevOps services you may already be using.

To follow along this tutorial you will need an Azure DevOps Org as well as a GitHub account/Org.

Creating a Git repository on GitHub

Start by creating a new GitHub repository.

1. On your GitHub account, in the upper-right corner of any page, use the '+' drop-down menu, and select New repository.

2. Type a name for your repository, add a description, select the repository visibility, select Initialize this repository with a README and click Create repository.

Creating an Azure DevOps project

Next we will create an Azure DevOps project.

1. Log into your Azure DevOps organisation and select New project.

2. Enter information into the form provided. Provide a name for your project, an optional description, choose the visibility, and select 'Git' as the source control type. Also select the work item process.

IMPORTANT: For the purposes of this tutorial I have created a 'public' GitHub repository and a 'private' Azure DevOps project. Depending on your project and requirements, ensure you select the right 'visibility' settings for your repository as well as your project.

Integrating Azure DevOps Boards with GitHub

Next we will connect and link DevOps boards to GitHub.

1. Choose 'Project Settings' and under the Boards section select 'GitHub connections'.

2. Choose Connect your GitHub account to use your GitHub account credentials. NOTE: Alternatively you can also connect to your GitHub account using a Personal Access Token (PAT) instead.

3. Next click 'Authorize AzureBoards'.

4. Select the GitHub repositories you want to link to Azure Boards and click 'Save'.

5. Review the selected repositories you want to link to Azure Boards and click on 'Approve, Install, & Authorize'.

6. You'll see the new GitHub connection under the project settings. You also have the ability to add/remove additional repositories or remove the GitHub connection entirely.

You can also review the Azure Boards application directly from your GitHub account/org by navigating to 'Settings' -> 'Integrations' -> 'Applications'

Example - Using DevOps Boards with GitHub

With Azure boards now connected to your GitHub repository, let's take a look at how you can link GitHub commits, pull requests, and issues to work items in Azure Boards using Codespaces.

Interacting with Azure boards from GitHub uses a special commit syntax called 'AB#{Id}' mention. What does this mean?

When you commit and push code changes to you source code, for any GitHub commit, pull request or issue, you can add the 'AB#{Id}' mention to create a link to your existing Azure Boards work items by entering the 'AB#{work item id}' mention within the text of a commit message. Or, for a pull request or issue, enter the 'AB#{Id}' mention within the title or description of the PR or issue. (not a comment).

Let's look at an example:

Create a new work item inside of your Azure Boards. In my case, my work item/user story specifies that I need to update the README.md file on my repository to give my team more details on an awesome feature I developed for my project:

Note down the work item 'ID'. In my case it is '3':

Since my repository is hosted on GitHub, I can make use of a Codespace, awesome! Check my previous blog post on how to set up Codepsaces.

Using my GitHub Codespace I can update my 'README.md' file, using my own branch I created called 'ML-updateDocs', and as a commit message for pushing the changes to source control I said: 'Update README.md - board work item AB#3'

After pushing my commit mentioning 'AB#3' in the commit message, notice that my committed code changes have now been linked with the Azure boards work item, and the work item is still in an 'Active' state:

I can also click and review the linked commit, which will take me straight into GitHub to show me exactly what changes were made to the file. (As you can see, I only removed an "empty space"):

Next I want to create a Pull Request to merge the new changes into the projects master/main branch, and remove my personal branch called 'ML-updateDocs', and as part of the pull request also close the Azure boards work item.

To close or transition work items from GitHub the system will recognize 'fix', 'fixes', 'fixed' applied to the 'AB#{Id}' mention item that follows.

You can create a pull request directly from your Codespace:

Notice that I prepend the word 'fixed' before my work item mention 'AB#3' in the description of the pull request:

Select 'Merge Pull Request' using your preferred method, 'Squash and Merge':

After the Squash Merge, you will have an option to delete/retain your local and remote branch, and optionally suspend Codespace:

Notice that my Azure board work item is now 'Closed', with a link to the Pull Request:

Here are more examples on how to transition board work items to a closed state:

Commit message	Action
Fixed AB#123	Links and transitions the work item to the "done" state.
Adds a new feature, fixes AB#123	Links and transitions the work item to the "done" state.
Fixes AB#123, AB#124, and AB#126	Links to Azure Boards work items 123, 124, and 126. Transitions only the first item, 123 to the "done" state.
Fixes AB#123, Fixes AB#124, Fixes AB#125	Links to Azure Boards work items 123, 124, and 126. Transitions all items to the "done" state.
Fixing multiple bugs: issue #123 and user story AB#234	Links to GitHub issue 123 and Azure Boards work item 234. No transitions.

Create a DevOps badge

You can also very easily create a status badges for your GitHub repo 'README.md' to show what work items are pending for example.

1. Navigate to your Azure DevOps Boards tab and select the configuration cog:

2. Copy the Azure boards status badge markdown sample. (Optional: Allow anonymous users to access the status badge and include all columns):

3. Paste the status badge markdown inside of the README.md file inside of your GitHub repository:

To summarise, Azure Boards-GitHub integration supports the following operational tasks:

• Create links between work items and GitHub commit, pull requests, and issues based on GitHub mentions.
• Support state transition of work items to a "Done" or "Completed" state when using GitHub mention by using fix, fixes, or fixed.
• Support full traceability by posting a discussion comment to GitHub when linking from a work item to a GitHub commit, pull requests, or issue.
• Show linked to GitHub code artifacts within the work item Development section.
• Show linked to GitHub artifacts as annotations on Kanban board cards.
• Support status badges of Kanban board columns added to GitHub repositories.

Integrating DevOps Pipelines with GitHub

Next let's look at how you can integrate and even trigger your Azure DevOps Pipelines from your GitHub repository.

GitHub does also offers it's very own automation platform, very similar to Azure DevOps Pipelines, called GitHub Actions, it even shares an almost identical YAML syntax and structure for building state of the art automation workflows. I won't be going into GitHub Actions in this post, but I highly recommend migrating your Azure DevOps pipelines to GitHub actions where applicable.

But for the purpose of this tutorial I will be showing you how you can integrate Azure DevOps pipelines with GitHub.

1. In your DevOps project, navigate to Pipelines and select Create Pipeline.

2. Next click on GitHub.

3. Next click 'Autorize AzurePipelines' (Requires authentication).

4. Select the GitHub repository where you want to link your Azure Pipelines.

5. Review the selected repository you want to link to and click on 'Approve & Install'.

6. After the AzurePipelines application is installed on your GitHub account, select a pipeline template. NOTE: My Azure DevOps project is 'Private' whilst my GitHub repository is 'Public', visibility of both Project and repositories can be amended accordingly.

7. Amend the path and filename for your pipeline. In my case I used 'AzurePipelines/hello-world.yml', and select 'Save and run'

Notice that the pipeline run completed successfully and can be checked from Azure DevOps, but the YAML file is stored on the GitHub repository you selected.

You can also edit the Azure Pipeline YAML file stored on your GitHub repository directly from Azure Devops by selecting 'Edit pipeline' (Requires authorisation).

Additionally, the Azure Pipelines App we installed on GitHub also integrates GitHub Checks which allows for sending detailed information about the Azure DevOps pipeline status and test, code coverage, and errors.

Now you can fully manage your Azure DevOps Pipelines using Codespaces as they are hosted on your GitHub repository. Pretty neat!

NOTE: Learn all about pipeline triggers as well by looking at CI triggers and PR triggers to automatically trigger pipeline runs.

Conclusion

Now that you have integrated Azure DevOps Pipelines and Boards with your GitHub repository you can make full use of Codespaces (and other great services on GitHub) to work on your applications and code without the need for a dedicated "developer workstation", and have the added benefit of being able to still use features such as Azure Boards and Azure Pipelines tightly integrated with your project.

I hope you have enjoyed this post and have learned something new. You can also find the code samples used in this blog post on my published GitHub page. ❤️

Author

Like, share, follow me on: 🐙 GitHub | 🐧 X/Twitter | 👾 LinkedIn

Marcel.LFollow

Dual Microsoft MVP DevOps + Azure | DevOps Architect | Technical speaker focused on Microsoft technologies, IaC and automation in Azure. Find me on GitHub: https://github.com/Pwd9000-ML