Azure Repos & Branching Strategies

Master Git-based version control in Azure DevOps — repositories, branch policies, pull request workflows, merge strategies, and branching models that keep your codebase stable and your team productive.

🧒 Simple Explanation (ELI5)

Imagine a team of artists all working on the same giant painting. If everyone just paints on one canvas at the same time, it's chaos — someone paints a tree where someone else was painting a cloud, colors get mixed up, and nobody knows who changed what.

Version control is like giving each artist their own transparent overlay sheet. Everyone draws on their own sheet. When they're happy with their work, they hold it up and say "Hey team, I'd like to add this to the master painting." The team reviews it, checks it doesn't clash with other changes, and then carefully layers it onto the main canvas.

• Azure Repos = the art studio — it stores every version of the painting, every overlay sheet, and a full history of every brushstroke ever made
• A branch = a transparent overlay sheet — your personal workspace where you make changes without disturbing the main painting
• A pull request (PR) = holding up your sheet for review — teammates check your work, leave comments, and approve before it's merged
• Merge = carefully layering your approved changes onto the master painting
• Branch policies = the studio rules — "at least two artists must approve," "the manager must verify it doesn't break anything," "you can't glue your sheet on without a review"

Without branching? Developers push directly to the main codebase, bugs land in production instantly, and nobody reviews anything. It's the equivalent of all artists painting on the same canvas with no coordination — guaranteed collisions and messes that take hours to untangle.

🔧 Technical Explanation

Git vs. TFVC in Azure Repos

Azure Repos supports two version control systems. Git is the default and recommended choice for all new projects.

Azure Repos Key Features

• Unlimited free private repositories — no per-repo pricing. Each project can have multiple repos (mono-repo or multi-repo).
• Web-based editor — edit files, create commits, and make PRs directly in the browser without cloning.
• Code Search — semantic search across all repos in your organization. Find classes, methods, and code patterns instantly.
• Rich diff viewer — inline and side-by-side diffs, syntax highlighting, and blame annotations in the web UI.
• Git LFS support — store large binary files (images, videos, ML models) in Git Large File Storage without bloating your repo.
• Forks — create server-side forks for open-source-style contribution models within your organization.
• GitHub Advanced Security for Azure DevOps (GHAzDO) — secret scanning, dependency scanning, and code scanning integrated directly into Azure Repos.

Branch Policies

Branch policies are rules that enforce code quality and team governance on protected branches (typically main, develop, and release/*). They're configured per branch (or branch pattern) in Project Settings → Repositories → Policies.

Pull Request Workflow

Pull requests are the core collaboration mechanism in Azure Repos. Here's the complete lifecycle:

1. Developer creates a branch from main (e.g., feature/user-login)
2. Developer writes code, makes commits, and pushes the branch to the remote
3. Developer opens a PR — sets a title, description, links work items, and requests reviewers
4. Build validation runs automatically — CI pipeline triggers on the PR branch. If it fails, the PR is blocked.
5. Reviewers review the code — leave inline comments, suggest changes, request modifications, or approve
6. Developer addresses feedback — pushes additional commits. If "reset votes on push" is enabled, reviewers re-approve.
7. All policies pass — required reviewers approved, build succeeded, comments resolved, work item linked
8. PR is merged — using the allowed merge strategy (squash, rebase, or merge commit)
9. Branch is deleted — the feature branch is cleaned up automatically (if configured)

Merge Strategies

Azure Repos supports four merge strategies. Understanding when to use each is critical for maintaining a clean Git history.

1. Merge Commit (No Fast-Forward)

Creates a merge commit that joins the feature branch into the target. All individual commits from the feature branch are preserved in history.

# History after merge commit:
*   M  Merge PR #42: feature/login → main
|\
| * C3  Add login validation
| * C2  Add login form
| * C1  Create auth module
|/
* B  Previous commit on main

Pros: Full history preserved, easy to see what belonged to a feature branch.
Cons: History can get noisy with many branches. Hard to read linear log.
Best for: Teams that value complete history and traceability.

2. Squash Merge

Combines all commits from the feature branch into a single commit on the target branch. The feature branch history is discarded.

# History after squash merge:
* S  Add user login feature (squashed from PR #42)
* B  Previous commit on main

# The 3 individual commits (C1, C2, C3) are gone from main's history

Pros: Clean, linear history. Each PR = one commit. Easy to revert an entire feature.
Cons: Loses granular commit history. Can't see intermediate steps.
Best for: Most teams — the recommended default. Feature history lives in the PR; main stays clean.

3. Rebase

Replays each commit from the feature branch on top of the target branch, creating new commit hashes. No merge commit.

# History after rebase:
* C3' Add login validation
* C2' Add login form
* C1' Create auth module
* B   Previous commit on main

# Commits are replayed with new hashes (C1', C2', C3')

Pros: Linear history with all individual commits preserved.
Cons: Rewrites history (new hashes). Can cause issues if commits aren't well-structured.
Best for: Teams with disciplined commit hygiene who want linear history without squash.

4. Semi-Linear Merge (Rebase + Merge Commit)

First rebases the feature branch on the target, then creates a merge commit. Combines linear history with merge context.

# History after semi-linear merge:
*   M  Merge PR #42: feature/login → main
|\
| * C3' Add login validation
| * C2' Add login form
| * C1' Create auth module
|/
* B   Previous commit on main

Pros: Clean merge topology — every feature branch is based on the latest main.
Cons: More complex. Requires the branch to be up-to-date with main before merging.
Best for: Teams that want the structure of merge commits but the cleanliness of rebased branches.

Branching Strategies: Git Flow vs. Trunk-Based Development

Your branching strategy defines how your team organizes branches and manages the flow of code from development to production. The two dominant strategies are Git Flow and Trunk-Based Development.

Git Flow

A structured model with multiple long-lived branches for different stages of development:

• main — always reflects production. Every commit is a release. Tagged with version numbers.
• develop — integration branch where features are merged. Represents the next release.
• feature/* — short-lived branches off develop for new features. Merged back to develop via PR.
• release/* — branched from develop when preparing a release. Bug fixes go here. Merged to both main and develop.
• hotfix/* — branched from main for critical production fixes. Merged to both main and develop.

Best for: Teams with scheduled releases, multiple versions in production, or long QA cycles.

Trunk-Based Development

A simpler model where all development happens on a single branch (main) with very short-lived feature branches:

• main (trunk) — the single source of truth. Deployable at all times.
• feature/* — ultra-short-lived branches (hours to 1–2 days max). Merged via PR with squash.
• No develop, release, or hotfix branches — everything goes through main.
• Feature flags — incomplete features are hidden behind feature flags (LaunchDarkly, Azure App Configuration) so code can be merged to main without being exposed to users.
• Continuous deployment — every merge to main triggers a deployment to production (or at least to staging).

Best for: Teams practicing continuous delivery/deployment, microservices, and modern cloud-native workflows.

📊 Branching Strategy Comparison

🛠️ Hands-on: Branches, Policies & Pull Requests

Follow these steps to set up a professional branching workflow in Azure DevOps from scratch.

Prerequisites

• An Azure DevOps project with a Git repository (created in Lesson 1)
• Git installed locally (git --version should return 2.x+)
• A Personal Access Token with Code (Read & Write) scope

Step 1: Clone the Repository

# Clone via HTTPS (use your PAT as the password when prompted)
git clone https://dev.azure.com/{org}/{project}/_git/{repo}
cd {repo}

# Verify you're on the main branch
git branch
# * main

Step 2: Create a Feature Branch

# Create and switch to a new feature branch
git checkout -b feature/user-authentication

# Verify you're on the new branch
git branch
#   main
# * feature/user-authentication

# Make some changes
echo "# Authentication Module" > auth.md
echo "def login(user, password):" > auth.py
echo "    return authenticate(user, password)" >> auth.py

# Stage and commit
git add .
git commit -m "feat: add authentication module skeleton"

# Push the branch to Azure Repos
git push -u origin feature/user-authentication

Step 3: Set Branch Policies on main

Configure branch policies in the Azure DevOps web UI:

1. Navigate to Project Settings → Repositories → your repo → Policies
2. Under Branch Policies, select the main branch
3. Configure the following policies:

✅ Require a minimum number of reviewers
   → Minimum reviewers: 2
   → Allow requestors to approve their own changes: No
   → Reset code reviewer votes when there are new changes: Yes

✅ Check for linked work items
   → Required

✅ Check for comment resolution
   → Required

✅ Limit merge types
   → ✅ Squash merge
   → ❌ Basic merge (no fast-forward)
   → ❌ Rebase and fast-forward
   → ❌ Rebase with merge commit

Step 4: Add Build Validation

Still on the branch policies page for main:

1. Scroll to Build Validation and click "+ Add build policy"
2. Select your CI pipeline (e.g., MyApp-CI)
3. Set the trigger to "Automatic" — the build runs on every PR update
4. Set "Policy requirement" to "Required" — PR cannot be merged unless the build passes
5. Set a display name: CI Build Validation
6. Set build expiration: "Immediately when main is updated" — if someone else merges to main before you, your validation re-runs

Step 5: Create a Pull Request

# Push your latest changes
git push origin feature/user-authentication

Then in the Azure DevOps web UI:

1. Navigate to Repos → Pull Requests → "New pull request"
2. Set source: feature/user-authentication → target: main
3. Title: feat: add user authentication module
4. Description: explain what the PR does, why, and any testing notes
5. Link a work item: click "Link work items" and select the related user story
6. Add reviewers: select team members from your project
7. Click "Create"

# Install Azure DevOps CLI extension
az extension add --name azure-devops

# Sign in
az devops configure --defaults organization=https://dev.azure.com/{org} project={project}
az login

# Create PR from command line
az repos pr create \
  --repository {repo} \
  --source-branch feature/user-authentication \
  --target-branch main \
  --title "feat: add user authentication module" \
  --description "Adds the auth module skeleton with login function" \
  --work-items 1234

Step 6: Review and Merge the PR

1. Reviewers open the PR, review the diff, leave inline comments
2. The author addresses comments and pushes fixes (votes reset if configured)
3. Reviewers approve — the "Approve" button shows a green checkmark
4. All policies pass: ✅ Reviewers, ✅ Build passed, ✅ Comments resolved, ✅ Work item linked
5. Click "Complete" → set merge type to "Squash commit"
6. Check "Delete feature/user-authentication after merging"
7. Click "Complete merge"

Step 7: Clean Up Locally

# Switch back to main and pull the merged changes
git checkout main
git pull origin main

# Delete the local feature branch (it's been merged and deleted on remote)
git branch -d feature/user-authentication

# Prune remote-tracking branches that no longer exist on the server
git fetch --prune

# Verify clean state
git log --oneline -5
# abc1234 feat: add user authentication module (squashed)

Essential Git Commands Reference

# ===== BRANCHING =====
git branch                           # List local branches
git branch -r                        # List remote branches
git branch -a                        # List all branches (local + remote)
git checkout -b feature/new-thing    # Create and switch to new branch
git switch -c feature/new-thing      # Same as above (modern Git syntax)
git branch -d feature/merged-branch  # Delete a local branch (safe — only if merged)
git branch -D feature/force-delete   # Force-delete a local branch (use with caution)
git push origin --delete feature/old # Delete a remote branch

# ===== REBASING & UPDATING =====
git fetch origin                     # Download remote changes without merging
git pull --rebase origin main        # Pull main and rebase your branch on top
git rebase main                      # Rebase current branch onto main
git rebase --abort                   # Cancel an in-progress rebase

# ===== STASHING =====
git stash                            # Save uncommitted changes temporarily
git stash pop                        # Restore stashed changes
git stash list                       # List all stashes

# ===== LOG & HISTORY =====
git log --oneline --graph --all      # Visual branch graph
git log --author="name" --since="2 weeks ago"  # Filter by author and date
git blame path/to/file.py           # See who changed each line and when
git diff main..feature/branch        # Compare two branches

# ===== UNDOING =====
git reset --soft HEAD~1              # Undo last commit, keep changes staged
git reset --hard HEAD~1              # Undo last commit AND discard changes (DANGEROUS)
git revert abc1234                   # Create a new commit that undoes a specific commit (safe)

🐛 Debugging Scenarios

Scenario 1: "PR Stuck in Waiting — Build Validation Failing"

Symptom: Your PR shows "1 check failed" or "Waiting for build validation." The Complete button is disabled.

Root Causes & Fixes:

• Build is genuinely failing: Click the failed check to open the build run. Check the logs — it could be a compilation error, failing test, or linting issue in your branch. Fix the code, commit, and push — the build re-triggers automatically.
• Build is queued but not running: Your organization may have hit the parallel job limit. Go to Organization Settings → Pipelines → Parallel Jobs to check. Free tier: 1 parallel job, 1,800 min/month. If at capacity, wait or purchase additional parallel jobs.
• Build pipeline was deleted or renamed: The branch policy still references an old build definition. Go to Project Settings → Repositories → Policies and update the build validation to point to the current pipeline.
• Build expires after main is updated: If someone else merged to main, your build validation may have expired (if "immediately when main is updated" is set). The build needs to re-run. Push a trivial commit or re-queue the build manually.

# Quick fix: update your branch with latest main to trigger a rebuild
git fetch origin
git rebase origin/main
git push --force-with-lease origin feature/your-branch

# --force-with-lease is safer than --force — it refuses to push
# if someone else has pushed to your branch since your last fetch

Scenario 2: "Cannot Push to Main — Branch Policy Violation"

Symptom: Running git push origin main returns an error like: "TF402455: Pushes to this branch are not permitted; you must use a pull request to update this branch."

Root Causes & Fixes:

• This is expected behavior! Branch policies prevent direct pushes to main. You must create a feature branch, push there, and open a PR.
• If you genuinely need to bypass (emergency): A Project Collection Administrator can push directly — but only if they have the "Bypass policies when pushing" permission. This should be used only for true emergencies and should be audited.
• If you committed to main locally by mistake:

# You accidentally committed to main locally. Move the commit to a feature branch:

# 1. Create a new branch from your current position (which has the accidental commit)
git branch feature/my-accidental-work

# 2. Reset main back to match the remote
git reset --hard origin/main

# 3. Switch to the feature branch and push
git checkout feature/my-accidental-work
git push -u origin feature/my-accidental-work

# 4. Now create a PR in the web UI

Scenario 3: "Merge Conflicts in Pull Request"

Symptom: The PR shows "This pull request has merge conflicts that must be resolved before it can be completed." Files are listed with conflict indicators.

Root Causes & Fixes:

• Another PR was merged to main that changed the same files. Your branch has diverged from main. You need to resolve conflicts by updating your branch.

# Option A: Rebase your branch onto latest main (preferred — cleaner history)
git fetch origin
git checkout feature/your-branch
git rebase origin/main

# If conflicts appear, Git will pause at each conflicting commit:
# 1. Open the conflicting files — look for conflict markers:
#    <<<<<<< HEAD
#    (your changes)
#    =======
#    (changes from main)
#    >>>>>>> origin/main

# 2. Edit the file to keep the correct code (remove all markers)

# 3. Stage the resolved file
git add path/to/resolved-file.py

# 4. Continue the rebase
git rebase --continue

# 5. Push (force-with-lease because rebase rewrites history)
git push --force-with-lease origin feature/your-branch

# ====================

# Option B: Merge main into your branch (simpler but creates a merge commit)
git fetch origin
git checkout feature/your-branch
git merge origin/main

# Resolve conflicts the same way (steps 1–3 above)
git add path/to/resolved-file.py
git commit   # Git auto-generates a merge commit message
git push origin feature/your-branch

Scenario 4: "Clone Authentication Failed"

Symptom: Running git clone returns fatal: Authentication failed for 'https://dev.azure.com/...'.

Root Causes & Fixes:

• Using your Microsoft password instead of a PAT: Azure DevOps HTTPS requires a Personal Access Token. Generate one from User Settings → Personal Access Tokens with Code (Read & Write) scope. Use it as the password.
• PAT expired or missing Code scope: Check your token in the Personal Access Tokens page. Create a new one if expired.
• Credential Manager caching stale credentials:

# Windows: Clear cached credentials
git credential-manager reject https://dev.azure.com

# Or use Credential Manager UI:
# Control Panel → Credential Manager → Windows Credentials
# Find and delete entries for "git:https://dev.azure.com"

# macOS: Clear from Keychain
git credential-osxkeychain erase <<EOF
host=dev.azure.com
protocol=https
EOF

# Linux: If using credential store
git config --global --unset credential.helper
# Then re-clone to be prompted for fresh credentials

# Alternative: Use SSH instead of HTTPS
# 1. Generate SSH key
ssh-keygen -t ed25519 -C "your-email@company.com"

# 2. Add public key to Azure DevOps:
#    User Settings → SSH Public Keys → + New Key
#    Paste contents of ~/.ssh/id_ed25519.pub

# 3. Clone with SSH URL
git clone git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

🎯 Interview Questions

🌍 Real-World Use Case

A FinTech Startup Taming Branch Chaos

Consider a FinTech startup with 12 developers, 4 microservices, and a history of production outages caused by untested code reaching production.

The problem:

• Developers pushed directly to main — no branch policies, no PR reviews
• Two production outages in one month caused by broken code that was never tested before deploy
• No branching strategy — some developers used develop, others pushed to main, others had personal branches lingering for weeks
• Merge conflicts were a daily nightmare — long-lived branches diverged significantly
• No traceability — impossible to answer "which user story caused this bug?"

What they implemented in Azure Repos:

• Trunk-Based Development — one main branch as the single source of truth. All feature branches live less than 2 days.
• Branch policies on main: 2 reviewers required, build validation (CI pipeline with unit + integration tests must pass), linked work items mandatory, squash merge only, comment resolution required.
• Path-based auto-reviewers: Changes to /services/payments/** auto-add the security team. Changes to /infrastructure/** auto-add the DevOps lead.
• Feature flags (Azure App Configuration): Incomplete features merged to main behind flags — code is always deployable even when features aren't ready.
• Naming convention: feature/AB#1234-short-description — every branch linked to a Board work item.

Results after 3 months:

• Production outages from untested code: 0 (down from 2/month)
• Average PR review time: under 4 hours (team SLA)
• Merge conflicts: reduced 80% — short-lived branches rarely diverge
• Full traceability: every production commit traces back to a user story, PR, CI build, and deployment
• Developer satisfaction: significantly improved — fewer firefights, cleaner workflow, clear process

📝 Summary