GitHub + Azure DevOps Integration Workshop Guide (30-Minute Edition)

Duration: 30 minutes
Format: Presentation + Discussion
Audience: Engineering Managers, Tech Leads, Decision Makers
Focus: Essential integration points and decision framework
Lab Guide: Hands-On Lab (Self-Paced) — optional after session

Note: This is the condensed 30-minute version for pilot sessions. For comprehensive coverage of security, governance, and advanced features, see Appendix A.

Workshop Overview

This 30-minute workshop covers how to layer Azure DevOps (ADO) integration on top of your existing GitHub Enterprise architecture. ADO integration is not a standalone architecture — it augments whichever base GitHub pattern you've chosen (EMU, Multi-Org, or Mixed Cloud + GHES).

Learning Objectives

By the end of this session, you'll understand:

• How ADO integration layers on top of GitHub architecture
• The AB# linking workflow (the primary integration point)
• How GitHub Copilot works with Azure Boards work items (and why GitHub repos are required)
• What PR Insights and additional integration features offer
• Whether ADO integration is right for your organization

Workshop Agenda

Total: 30 minutes

1. GitHub + ADO Architecture (3 min)

The Model

ADO integration sits on top of whichever base GitHub architecture you chose:

You still need a base pattern. ADO augments — it doesn't replace — your GitHub architecture.

Why Coexistence?

Most enterprises have significant Azure DevOps investment: work items, queries, dashboards, pipelines, test plans. The "better together" thesis uses the right tool for each job:

2. AB# Linking Explained (8 min)

The Syntax

Use AB#NNNNN in GitHub commit messages, PR descriptions, or issue descriptions to link to Azure DevOps work item #NNNNN.

Example Workflow

1. Dev picks up work — Grabs AB#4567 from ADO Boards
2. Creates branch — feature/AB4567-add-login in GitHub repo
3. Commits with reference — Message: Add OAuth login flow AB#4567
4. Opens PR — PR description mentions AB#4567 → ADO shows linked PR automatically
5. Merges PR — PR merged to main + commit says Fixes AB#4567 → ADO auto-transitions work item to Done
6. PM sees completion — ADO Boards dashboard now shows the work item as Done with linked GitHub activity

3. AB# in Practice (2 min)

Real Scenario: Plum Smart Performance Optimization

Setup: ADO work item AB#12340 — "Optimize query performance in Plum Smart checkout"

Developer flow:

Commit message: "Optimize DB index for checkout queries AB#12340"
PR description: "Closes AB#12340. Added composite index on transactions table. See attached performance benchmarks."
ADO result: Work item shows linked PR, commits, and associated GitHub branches in Development section
On PR merge: Work item automatically moves from "In Progress" → "Done"

Benefit: Project manager sees real-time progress in ADO Boards without switching to GitHub. Developers stay in their GitHub workflow.

4. Copilot from Azure Boards Work Items (3 min)

What It Is

Azure Boards now integrates with GitHub Copilot. From an ADO work item, you can delegate to Copilot for automated code generation and PR creation — directly from ADO Boards.

Governance Consideration

⚠️ Data flows from ADO to Copilot: Work item titles, descriptions, and comments are sent as context. Evaluate whether this meets your organization's data handling requirements. (Not used for model training in Copilot Enterprise.)

5. PR Insights & Additional Features (2 min)

PR Insights

View GitHub pull request status directly from ADO work items:

• PR draft status — Is it still a draft?
• Review status — Approved, changes requested, or waiting for review?
• Check status — CI status, policy compliance

Appears in the Development section of ADO work items. Project managers can track PR progress without leaving ADO Boards.

! Mentions

Use ! to reference and discuss GitHub pull requests from ADO work item text fields or comments:

!{org/repo}/pull/{pr-number}

Example: !microsoft/ghcp-content/pull/42 links discussion to that PR.

6. Decision Framework (5 min)

When to Add ADO Integration

✅ Add ADO integration when:

• You have significant ADO Boards investment (custom work items, queries, dashboards)
• You want Copilot + GHAS without disrupting existing workflows
• You're doing gradual migration from ADO Repos to GitHub
• Your PMs and stakeholders live in ADO Boards
• You use ADO Test Plans

When to Skip ADO Integration

⚠️ Skip ADO integration if:

• You're starting fresh — go all-in on GitHub from the start
• GitHub Projects V2 can replace ADO Boards (simpler = less overhead)
• Total cost of running both platforms > one-time migration cost
• Developers strongly prefer a single tool (context-switching harms productivity)

Key Pros & Cons

7. Q&A (4 min)

Open discussion. Questions to consider:

• How much of your team's workflow currently lives in ADO Boards?
• Could GitHub Projects V2 replace your ADO usage?
• Do you have ADO Pipelines that would be difficult to migrate?
• Is Entra ID your identity provider for both platforms?

Reference Materials

• AB# Linking Setup: Microsoft Learn Guide
• Integration Overview: Microsoft Learn
• Hands-On Lab (self-paced): Lab Guide

Appendix A: Comprehensive Content (For Reference)

This appendix contains the full sections from the 60–75 minute comprehensive workshop. Reference this for deep dives into security, governance, architecture, and advanced features.

A1. Integration Architecture Deep Dive

Full architecture diagram and detailed explanation of data flows between GitHub and ADO systems.

A2. Security, Governance & Connection Overview

Connection Setup

• Admin Permissions required: GitHub org admin, ADO Project Collection Administrator
• Repo Limit: Up to 1,000 repositories per connection
• Org Limit: One connection per GitHub organization

Authentication Options

Audit & Governance

Troubleshooting Quick Reference

A3. Advanced Features

ADO Pipelines Building from GitHub Repos

Even when source code lives in GitHub, ADO Pipelines can still build it:

1. In Azure DevOps: Project Settings → Service Connections → New → GitHub
2. Authorize the connection to the target GitHub org
3. In ADO Pipeline YAML, reference the GitHub repo:

resources:
  repositories:
    - repository: my-github-repo
      type: github
      endpoint: github-connection
      name: org/repo-name

Test Plans & Artifacts

Azure DevOps Test Plans and Artifacts remain the leading tools in these domains with no GitHub equivalents.

A4. Comprehensive Decision Matrix

A5. Migration Roadmap Example

Phase 1 (Months 1–3): GitHub + ADO Coexistence

• New projects start in GitHub
• ADO Boards remains the PM system
• AB# linking tracks GitHub PRs in ADO work items

Phase 2 (Months 4–12): Gradual ADO Repos → GitHub Migration

• Migrate critical repos to GitHub
• Evaluate GitHub Projects V2 as ADO Boards alternative
• ADO Pipelines → GitHub Actions for new CI/CD

Phase 3 (Year 2+): ADO Sunset (Optional)

• All source code in GitHub
• ADO Boards → GitHub Projects (if suitable)
• Decommission ADO when benefits of coexistence diminish

End of Appendix