This Azure DevOps error occurs when you try to push directly to a branch that has branch policies enabled. The branch requires changes to go through pull requests rather than direct commits.
When you encounter TF402455 in Azure DevOps (formerly VSTS/TFS), it means the target branch has branch policies configured that prevent direct pushes. Azure DevOps is enforcing your team's code quality and change management standards by requiring pull requests for all changes. Branch policies in Azure DevOps can include: - Minimum number of reviewers required - Build validation (CI must pass) - Work item linking requirements - Comment resolution checks - Required reviewers for specific paths The error message "Pushes to this branch are not permitted; you must use a pull request to update this branch" tells you exactly what's happening—the branch is protected and direct pushes are blocked by policy. This commonly occurs when: - Developers try to push directly to main, master, or release branches - CI/CD pipelines attempt to commit version bumps or changelog updates - Scripts or automation tools try to push without proper bypass permissions - Team members are unfamiliar with the repository's branch policy configuration
The intended solution is to use a pull request instead of pushing directly:
# Create a feature branch from your current work
git checkout -b feature/your-changes
# Make your changes and commit
git add .
git commit -m "Your changes"
# Push the feature branch (not the protected branch)
git push -u origin feature/your-changesThen create a pull request in Azure DevOps:
1. Go to Repos > Pull requests
2. Click "New pull request"
3. Select your feature branch as source and the protected branch as target
4. Complete the required reviews and checks
5. Merge the pull request
Review what policies are blocking your push:
1. Navigate to your Azure DevOps project
2. Go to Repos > Branches
3. Find your protected branch (e.g., main)
4. Click the ... menu and select Branch policies
Review which policies are enabled:
- Require a minimum number of reviewers - requires PR approvals
- Check for linked work items - requires work item association
- Check for comment resolution - all comments must be resolved
- Build validation - requires passing CI builds
- Automatically included reviewers - specific people must review
Each enabled policy contributes to blocking direct pushes.
If your CI/CD pipeline needs to push directly (e.g., for version bumps):
1. Go to Project Settings > Repositories
2. Select your repository
3. Go to the Security tab
4. Find the build service account:
- For project-scoped: [Project Name] Build Service ([Organization])
- For collection-scoped: Project Collection Build Service ([Organization])
5. Set Bypass policies when pushing to Allow
Note: Check your pipeline settings. If "Limit job authorization scope to current project" is disabled, use the collection-scoped identity.
# In your pipeline, you may need to configure git
- script: |
git config user.email "[email protected]"
git config user.name "Build Service"
git push origin HEAD:main
displayName: 'Push changes'For more granular control, set bypass at the branch level:
1. Go to Repos > Branches
2. Find your protected branch
3. Click ... > Branch security
4. Locate the user, group, or service account
5. Set these permissions:
- Bypass policies when pushing: Allow
- Bypass policies when completing pull requests: Allow (if needed)
Important: These permissions override branch policies only for the specified identities. Other users will still need to follow the PR workflow.
For specific users who need temporary bypass:
1. Add them individually to the branch security
2. Grant bypass permissions
3. Remove after the task is complete
Sometimes policies are set at the project level and cannot be overridden:
1. Go to Project Settings > Repositories > Policies
2. Check for cross-repository policies that apply to all repos
3. Review if these policies are enforced on your branch
If project-level policies are blocking you:
- You may need Project Administrator permissions to modify them
- Consider whether the policies should be adjusted or if you should use the PR workflow
- Contact your Azure DevOps administrator if you lack permissions
Note: Project-level policies appear as non-editable toggles in branch-level settings.
If you're getting TF402455 when trying to delete a branch:
Option 1: Remove policies before deletion
1. Go to Repos > Branches > Branch policies
2. Disable all policies on the branch
3. Delete the branch
4. This works for feature branches that are no longer needed
Option 2: Use Azure DevOps UI
1. Go to Repos > Branches
2. Find the branch to delete
3. Click the ... menu > Delete branch
4. Some UI operations may succeed where git commands fail
Option 3: Grant delete permissions
1. Go to branch security settings
2. Ensure you have Force push (rewrite history, delete branches) set to Allow
If you're using semantic-release or similar tools:
1. Create a Personal Access Token (PAT) with Code (Read & Write) permissions
2. Add it as a pipeline variable (e.g., GIT_CREDENTIALS)
3. Configure the pipeline:
variables:
- name: GIT_CREDENTIALS
value: $(System.AccessToken) # or your PAT secret
steps:
- checkout: self
persistCredentials: true
- script: |
git config user.email "[email protected]"
git config user.name "Semantic Release"
displayName: 'Configure git'
- script: npx semantic-release
displayName: 'Run semantic-release'
env:
GH_TOKEN: $(GIT_CREDENTIALS)Alternative: Configure semantic-release to create a PR instead of pushing directly using plugins like @semantic-release/git with PR creation.
### Why Branch Policies Exist
Branch policies aren't bugs—they're features designed to protect your codebase. Before bypassing them, consider if the protection is intentional. Bypassing policies removes safeguards like:
- Code review requirements
- CI/CD validation
- Work item traceability
### Project Collection vs Project Build Service
Azure DevOps has two build service identities:
- Project Build Service: Scoped to a single project ([Project] Build Service ([Org]))
- Project Collection Build Service: Can access resources across projects
If your pipeline has "Limit job authorization scope to current project" enabled (recommended), use the project-scoped identity. If disabled, use the collection-scoped identity.
### Force Push Considerations
Even with bypass permissions, force push may require additional permissions:
- Force push (rewrite history, delete branches) must be set to Allow
- This is separate from the bypass policies permission
- Force push can be dangerous—use with caution
### Common Pipeline Patterns
For pipelines that need to commit (version bumps, changelog updates):
1. Best: Create a PR from the pipeline instead of pushing directly
2. Acceptable: Grant bypass to the build service for specific branches only
3. Risky: Grant broad bypass permissions (avoid if possible)
### Azure DevOps vs GitHub
This error (TF402455) is specific to Azure DevOps. Similar functionality exists in:
- GitHub: "GH006: Protected branch update failed"
- GitLab: "You are not allowed to push code to protected branches"
- Bitbucket: "Push rejected: branch restrictions"
Each platform has different configuration options but the concept is the same.
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git