How to fix TF402116: Push rejected because a work item is required in Git

The simplest fix is to include a work item reference in your commit message using the hash syntax:

git commit -m "Fix login validation bug #42"

Or if you need to amend your last commit:

git commit --amend -m "Fix login validation bug #42"

Replace 42 with your actual work item ID from Azure Boards. The # symbol is required - Azure DevOps won't recognize bare numbers.

You can link multiple work items in a single commit by including multiple references:

git commit -m "Implement feature #123 and fix related bug #456"

Or use a more structured format:

git commit -m "Add user profile page

Implements #123
Fixes #456
Related to #789"

All referenced work items will be automatically linked to the commit when pushed.

If you have commits that need to be amended with work item references, use interactive rebase:

# Rebase the last 3 commits (adjust number as needed)
git rebase -i HEAD~3

In the editor, change pick to reword for commits you want to modify:

reword abc1234 Original commit message
pick def5678 Another commit

Save and close. Git will prompt you to edit each marked commit message where you can add the work item reference.

Warning: Only do this for commits that haven't been pushed yet, or coordinate with your team if rebasing shared history.

If the branch policy blocks direct pushes, use a pull request workflow:

1. Create a feature branch:

git checkout -b feature/my-changes
git push -u origin feature/my-changes

2. Create a pull request in Azure DevOps and link work items in the PR interface

3. In Azure DevOps, navigate to Repos > Pull Requests > New Pull Request

4. In the Work Items section of the PR, click "Add work item" and search for the relevant work items

5. Complete the pull request to merge your changes

This approach is often preferred as it allows code review and provides better traceability.

You can also link work items after commits are pushed (before PR completion):

1. Go to Azure DevOps > Repos > Commits
2. Find your commit and click on it
3. In the commit details, click "Link work items"
4. Search for and select the relevant work items

Alternatively, from the work item side:

1. Open the work item in Azure Boards
2. Go to the "Development" section
3. Click "Add link" > "Existing item"
4. Select "Commit" as the link type
5. Enter the commit SHA or browse to find it

If commit mentions aren't being recognized, verify the repository settings:

1. Go to Project Settings > Repositories
2. Select your repository
3. Under Settings, ensure "Commit mention linking" is enabled
4. Also enable "Commit mention work item resolution" if you want mentions to update work item state

Note: These settings may be disabled by default for forked repositories. If you're working in a fork, you may need to request these settings be enabled.

In some cases, you may need to bypass the work item linking requirement:

1. Contact your Azure DevOps administrator
2. Request "Bypass policies when pushing" permission for the specific repository or branch

This permission allows you to push changes directly without meeting policy requirements. However, this should be used sparingly and only when necessary (e.g., emergency fixes, automated tooling).

To grant bypass permissions:
1. Go to Project Settings > Repositories > Security
2. Find the user or group
3. Set "Bypass policies when pushing" to Allow

Caution: Overusing bypass permissions defeats the purpose of having policies and reduces traceability.