https://github.com/joshjohanning/azdo_commit_message_validator
GitHub Action to enforce commits are linked to Azure Boards work items, and link the work item to the pull request
https://github.com/joshjohanning/azdo_commit_message_validator
actions azure-boards azure-devops github javascript node-action
Last synced: about 1 month ago
JSON representation
GitHub Action to enforce commits are linked to Azure Boards work items, and link the work item to the pull request
- Host: GitHub
- URL: https://github.com/joshjohanning/azdo_commit_message_validator
- Owner: joshjohanning
- License: mit
- Created: 2022-08-02T18:06:18.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-09T19:39:22.000Z (about 1 month ago)
- Last Synced: 2026-03-09T23:59:24.381Z (about 1 month ago)
- Topics: actions, azure-boards, azure-devops, github, javascript, node-action
- Language: JavaScript
- Homepage:
- Size: 8.93 MB
- Stars: 5
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Azure DevOps Commit/PR Validator and Commit+Pull Request Linker Action
[](https://github.com/joshjohanning/azdo_commit_message_validator/releases)
[](https://github.com/marketplace/actions/azure-devops-commit-validator-and-pull-request-linker)
[](https://github.com/joshjohanning/azdo_commit_message_validator/actions/workflows/ci.yml)
[](https://github.com/joshjohanning/azdo_commit_message_validator/actions/workflows/publish.yml)
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!
4. **Visibility & Tracking** - Work item linkages are added to the job summary for easy visibility
## Action Output
The action provides visibility into work items through the **Job Summary**:
- A summary of all work items found in commits and PR is added to the workflow run's job summary page
- Includes clickable links to commits and displays associated work items
- Shows which work items were **linked** to the PR (when `link-commits-to-pull-request` is enabled) vs. **verified** (when `validate-work-item-exists` is enabled)
- Provides a quick reference of work items associated with the PR
## Usage
This should only be triggered via pull requests.
```yml
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
# Skip runs triggered by azure-boards bot editing the PR body to avoid duplicate workflow runs
if: github.actor != 'azure-boards[bot]'
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 for `AB#xxx` (scope configurable via `pull-request-check-scope`) | `true` | `false` |
| `pull-request-check-scope` | Only if `check-pull-request=true`, where to look for `AB#` in the PR: `title-or-body`, `body-only`, or `title-only` | `false` | `title-or-body` |
| `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` |
| `validate-work-item-exists` | Validate that the work item(s) referenced in commits and PR exist in Azure DevOps (requires `azure-devops-token` and `azure-devops-organization`) | `false` | `true` |
| `add-work-item-table` | Add a "Linked Work Items" table to the PR body showing titles for `AB#xxx` references (original references are preserved). Requires `azure-devops-token` and `azure-devops-organization` | `false` | `false` |
| `append-work-item-title` | **Deprecated** - use `add-work-item-table` instead. Will be removed in a future major version. | `false` | `false` |
| `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 }}` |
| `comment-on-failure` | Comment on the pull request if the action fails | `true` | `true` |
## 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:
```json
"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](https://docs.microsoft.com/en-us/rest/api/azure/devops/wit/work-items/update?view=azure-devops-rest-7.1&tabs=HTTP#add-a-link), 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](https://developercommunity.visualstudio.com/t/artifact-uri-format-in-external-link-of-work-items/964448#T-N988703) for slightly more info.
Found the javascript sample [here](https://github.com/dc-ag/azure-devops-pr-notification/blob/fcb9cd24ffbcc2dbe81a7500a3d5577213afa7e3/lib/main.js). Other samples are [here](https://github.com/search?q=%22vstfs%3A%2F%2F%2FGitHub%22&type=code).