How to fix TF401028: Build validation failed in Git

If you're trying to push directly to a protected branch, you need to use a pull request instead:

Create a feature branch and push there:

# Create and switch to a new branch
git checkout -b feature/my-changes

# Push to the feature branch (this will work)
git push -u origin feature/my-changes

Create a pull request:
1. Go to Azure DevOps > Repos > Pull Requests
2. Click "New pull request"
3. Select your feature branch as source, protected branch as target
4. Fill in the title and description
5. Click "Create"

The build validation will trigger automatically. Once it passes, you can complete the PR.

Note: Direct pushes are blocked by design when branch policies are enabled. This is intentional to enforce code review and validation workflows.

When your pull request is open, check why the build is failing:

View build status:
1. Open your pull request in Azure DevOps
2. Look at the "Checks" or "Policies" section
3. Click on the build validation policy to see details
4. Click "View build" to see the full build log

Common build failures:
- Compilation errors: Fix code errors and push to your branch
- Test failures: Review failed tests and fix them
- Linting/code analysis issues: Address code style violations
- Missing dependencies: Update package references

To retry the build:

# Make fixes locally
git add .
git commit -m "Fix build errors"
git push

The build will automatically re-queue when you push changes to the PR source branch.

If the build cannot even be queued, check these common issues:

1. Pipeline and repository mismatch:
The pipeline must be created from the same repository as the pull request. If you created a pipeline from Repository A and try to use it for PRs in Repository B, it won't work.

2. Pipeline not visible in policy settings:
- Go to Project Settings > Repositories > [Your Repo] > Policies > [Branch]
- Under Build validation, check if your pipeline is selectable
- If not, run the pipeline at least once manually first

3. YAML file missing or invalid:
Ensure your pipeline YAML file exists in both the source and target branches:

# Check if azure-pipelines.yml exists
git ls-files | grep -i pipeline

# Validate YAML syntax (basic check)
cat azure-pipelines.yml

4. Permissions issues:
- Go to Project Settings > Pipelines > [Your Pipeline]
- Click "Security"
- Ensure "Build Administrators" and your user have "Queue builds" permission

5. Re-select the pipeline in branch policy:
- Go to Project Settings > Repositories > Policies > [Branch]
- Remove the old build validation policy
- Add a new one and select the correct pipeline

Build validation can expire if the target branch is updated after your PR build completed:

Check expiration settings:
1. Go to Project Settings > Repositories > [Repo] > Policies > [Branch]
2. Click on the build validation policy
3. Review "Build expiration" setting:
- "Immediately when branch updates" - Most strict
- "After N hours if branch updated" - Balanced
- "Never" - Build never expires (least strict)

Update your branch to re-trigger build:

# Fetch latest changes
git fetch origin

# Rebase your branch on the target
git rebase origin/main

# Push (force push if rebased)
git push --force-with-lease

Alternatively, merge the target branch into your feature branch:

git fetch origin
git merge origin/main
git push

This brings in the latest changes and triggers a new validation build.

In emergency situations, you may need to bypass build validation. This requires special permissions:

Two bypass permissions exist:
- Bypass policies when completing pull requests: Complete PRs even if policies aren't satisfied
- Bypass policies when pushing: Push directly to protected branches

To request bypass:
1. Contact your Azure DevOps Project Administrator
2. They can grant bypass permissions at project, repo, or branch level
3. Go to Project Settings > Repositories > [Repo] > Security
4. Find your user or group
5. Set "Bypass policies when completing pull requests" to Allow

Using bypass when completing PR:
1. Open your pull request
2. Click "Complete"
3. Check "Override branch policies and enable merge"
4. Complete the merge

Warning: Use bypass sparingly. It circumvents quality gates that protect your codebase. Document why bypass was needed.

A specific TF401028 error occurs when multiple clients try to update the same reference simultaneously:

Error message:

TF401028: The reference 'refs/heads/main' has already been updated by another client, so you cannot update it.

This happens when:
- Multiple CI/CD pipelines update the same branch
- Terraform or other automation tools conflict
- Parallel PR completions occur

Solutions:

1. Retry the operation:

git fetch origin
git pull --rebase origin main
git push

2. For Terraform Azure DevOps provider:
If using azuredevops_git_repository with default_branch:
- Remove initialization.init_type = "Clean" when using parent_repository_id
- Or set default_branch after initial repository creation

3. Implement retry logic in CI/CD:

# Azure Pipelines example with retries
- script: |
    for i in 1 2 3; do
      git push && break || sleep 5
    done
  displayName: 'Push with retry'

4. Use branch locks for critical operations:
Consider using Azure DevOps branch locks during sensitive operations to prevent concurrent updates.

Misconfigured branch policies are a common cause of build validation failures:

Review branch policies:
1. Go to Project Settings > Repositories
2. Select your repository
3. Go to Policies tab
4. Select the protected branch (e.g., main, develop)

Correct build validation setup:
1. Click "+" next to Build validation
2. Select your pipeline from the dropdown
3. Configure options:
- Trigger: Automatic (recommended) or Manual
- Policy requirement: Required (blocks merge) or Optional (advisory)
- Build expiration: Choose based on your workflow
- Display name: Descriptive name for the check
4. Optionally add path filters to limit which files trigger validation

Path filters example:

# Include only src folder changes
/src/*

# Exclude documentation
!/docs/*

Test the configuration:
1. Create a test PR with a small change
2. Verify the build triggers automatically
3. Check that the PR shows the build status
4. Confirm merge is blocked until build passes

Common misconfigurations:
- Wrong pipeline selected
- Pipeline from different repository
- Path filters excluding all changes
- Policy set to "Optional" when "Required" was intended