Azure DevOps Commit/PR Validator and Commit+Pull Request Linker Action

This action validates that pull requests and commits contain Azure DevOps work item links (e.g. AB#123), and automatically links the GitHub Pull Request to work items found in commit messages.

Key Features

1. Validates Pull Requests - Ensures PR title or body contains an Azure DevOps work item link (e.g. AB#123)
2. Validates Commits - Ensures each commit in a pull request has an Azure DevOps work item link (e.g. AB#123) in the commit message
3. Automatically Links PRs to Work Items - When a work item is referenced in a commit message, the action adds a GitHub Pull Request link to that work item in Azure DevOps
   • 🎯 This is the key differentiator: By default, Azure DevOps only adds the Pull Request link to work items mentioned directly in the PR title or body, but this action also links work items found in commit messages!

Usage

This should only be triggered via pull requests.

name: pr-commit-message-enforcer-and-linker

on:
  pull_request:
    branches: ["main"]
    types:
      - opened
      - synchronize
      - reopened
      - edited # can re-run without code changes

jobs:
  pr-commit-message-enforcer-and-linker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
      - name: Azure DevOps Commit Validator and Pull Request Linker
        uses: joshjohanning/azdo_commit_message_validator@v2
        with:
          check-pull-request: true
          check-commits: true
          fail-if-missing-workitem-commit-link: true
          link-commits-to-pull-request: true
          azure-devops-organization: my-azdo-org
          azure-devops-token: ${{ secrets.AZURE_DEVOPS_PAT }}

Inputs

Name	Description	Required	Default
check-pull-request	Check the pull request body and title for AB#xxx	true	true
check-commits	Check each commit in the pull request for AB#xxx	true	true
fail-if-missing-workitem-commit-link	Only if check-commits=true, fail the action if a commit in the pull request is missing AB# in every commit message	false	true
link-commits-to-pull-request	Only if check-commits=true, link the work items found in commits to the pull request	false	true
azure-devops-organization	Only if check-commits=true, link the work items found in commits to the pull request	false	''
azure-devops-token	Only required if link-commits-to-pull-request=true, Azure DevOps PAT used to link work item to PR (needs to be a full PAT)	false	''
github-token	The GitHub token that has contents-read and pull_request-write access	true	${{ github.token }}

Setup

Runner Software Requirements

Required software installed on runner:

• bash (tested with ubuntu-latest runner)
• gh (GitHub CLI)
• jq
• grep
• cut

Screenshots

Failing pull request, including comment back to the pull request showing why it failed

Failing commit

Adding Pull Request link in Azure DevOps to work item linked to a commit in a pull request

Validating the logs and creating pull requests

How the commit / pull request linking in Azure DevOps works

If the check-commits: true the action will look at each commit in the pull request and check for AB#123 in the commit message.

The action loops through each commit and:

1. Makes sure it has AB#123 in the commit message
2. If it does, and if link-commits-to-pull-request: true, add a GitHub Pull Request link to the work item in Azure DevOps

Adding the link to the GitHub Pull Request was the tricky part.

If you use an API to look at the links of a work item with a GitHub pull request link, you will see:

      "attributes": {
        "authorizedDate": "2022-08-02T18:45:03.567Z",
        "id": 3916078,
        "name": "GitHub Pull Request",
        "resourceCreatedDate": "2022-08-02T18:45:03.567Z",
        "resourceModifiedDate": "2022-08-02T18:45:03.567Z",
        "revisedDate": "9999-01-01T00:00:00Z"
      },
      "rel": "Artifact Link",
      "url": "vstfs:///GitHub/PullRequest/62f33e8a-c421-441d-88e1-06c46c4ffbbb%2f7"

Note the url field - vstfs:///GitHub/PullRequest/62f33e8a-c421-441d-88e1-06c46c4ffbbb%2f7

Creating a new link is (relatively) easy with the API, but you can't just use the regular GitHub pull request link. They use a garbled GUID that isn't the GUID or ID of the repo in GitHub.

The GUID can be found using an (undocumented) API:

POST https://dev.azure.com/%DEVOPS_ORG%/_apis/Contribution/dataProviders/query?api-version=7.1-preview.1

See this thread for slightly more info.

Found the javascript sample here. Other samples are here.