GitHub for Azure DevOps migrants

GitHub and ADO cover the same ground with a much smaller feature set. The danger is not the concepts that are missing — those are obvious. It is the ones that map almost, where a familiar word means something different and the process quietly breaks weeks later.

If your team's Azure DevOps or TFS project uses TFVC rather than Git repos, everything below is the wrong layer to start at. This mapping table is GitHub-vs-ADO process vocabulary — work items, boards, pipelines. TFVC vs Git is a different, more fundamental jump: TFVC checks files out from one central server one at a time, and only one person can hold the lock on a file at once; Git gives every clone the entire history, and every commit happens locally, before anyone pushes anywhere — there's no central lock to wait for. No amount of relabeling nouns bridges that gap; it has to be learned as its own concept before the table below is useful. If this repository's colleague-training program is available, its education/0_prerequisites/module-0-1-what-is-version-control.md (this repository only) covers the concept in plain terms — but the two sentences above are enough to name the jump even without it.

The single most expensive mistake (once you're on Git): treating milestones as sprints. See below.

Mapping table

The three traps

1. Milestones are not sprints

A milestone is a delivery bucket — a release, or a phase. It closes when the thing ships. It has a due date, which makes it look like an iteration, and that is the trap.

Time-boxed iterations belong in a Projects iteration field. Using milestones as sprints leaves a graveyard of stale, half-empty Sprint 14 milestones that nobody closes, and destroys the one thing milestones are good at: answering "what is in the next release?"

If you want both — you probably do — run milestones for releases and an iteration field on the board for cadence. They are different axes, like priority and milestone. Note that the iteration field cannot be created from the CLI (gh project field-create supports only TEXT, SINGLE_SELECT, DATE, NUMBER); use the web UI or a GraphQL mutation. See github-projects.

2. Issue types are org-only

gh issue create --type Bug sets a first-class type, separate from labels — the closest thing to a Work Item Type. But issue types are defined at the organization level. On a personal account the API returns 404 and the flag has nothing to select:

gh api "orgs/<org>/issue-types" --jq '.[].name'    # 404 on a personal account

On a personal repo, encode the type as a category label and move on. If you are setting up an org, define issue types early — retrofitting them across an existing backlog is manual. Keep them coarse (Bug, Feature, Task, Epic); the priority and area axes stay on labels.

3. A new Wiki is a trap; an established one is not

GitHub's Wiki is a separate git repo with no pull requests, no review, no CI, and no coupling to the branch that changed the behaviour it documents. For a repository with no Wiki in use, docs that matter go in docs/ in the repo, where they are versioned with the code, reviewed in the same PR, and greppable. Don't enable a Wiki to hold them.

That is a rule about starting one, not about an existing one. Azure DevOps also has a Git-backed project Wiki, so a team arriving with an established, actively-used Wiki (here or there) may keep it: leave it alone and treat its content as the source of truth for what it covers, as github-repo-bootstrap does. If they are migrating because the wiki sprawled unreviewed, that is the moment to suggest docs/, but it is a call about their wiki, not about wikis in general.

Use Discussions for the conversational content that would have been a wiki page in ADO (how-do-I, RFCs, announcements).

What GitHub has that ADO does not

Discussions is the one to actually learn. ADO has no equivalent, so migrants tend to keep putting exploratory work into issues, where it rots as a stale never-closeable ticket.

• Discussion = exploring. Threaded, votable, answer-markable, no assignee, no "when will this be done."
• Issue = committed to doing. Assignee, priority, milestone.
• Converting a discussion to an issue is the moment exploration became commitment — that boundary is the whole value.

Categories worth having: Ideas, Q&A, RFC, Announcements.

Caveat: gh discussion is in preview and subject to change. Script against the GraphQL API if you need stability; the web UI is fine for humans.

Also new relative to ADO: CODEOWNERS (automatic review routing by path), Dependabot (dependency PRs raised for you), auto-generated release notes, and native sub-issues.

The traceability chain

The consistency that ADO gave you through work-item links, GitHub gives through one chain. Every change follows it, and each link is enforced by the tool rather than by discipline:

issue (#N, priority + category labels, milestone)
  → gh issue develop <N>        # branch created AND linked to the issue
  → PR with "Refs #N"           # links partial or in-progress delivery
  → criteria + evidence reviewed # acceptance contract must pass
  → change "Refs" to "Closes"   # completed issue may now auto-close
  → milestone                   # groups the release
  → auto-generated release notes # built from merged PRs

Break any link and traceability is back to human memory. gh issue develop is the one most often skipped and the one that does the most work — it is the equivalent of creating a branch from a work item in ADO.

GitHub does not enforce acceptance criteria the way a configured ADO process can. Closes #N merely changes state when the PR merges; it does not evaluate a checkbox. Treat each criterion as part of the work: map it to concrete evidence, check it only when satisfied, and keep Refs #N plus an open issue while any in-scope criterion is unmet or unevaluated. Scope changes require a recorded decision, not a checkbox that falsely implies delivery. The exact merge and closure gate lives in github-hygiene.

Keeping Azure Boards next to GitHub

Many teams move the code first and keep Azure Boards for planning. The two link through the AB# mention, which needs the Azure Boards project to be connected to the GitHub repository first (the Azure Boards app for GitHub, with Contributor access to both). Without the connection a mention links nothing.

• Where it works: put AB#125 in a commit message, a pull request description or an issue description, push or save, and the work item shows the link in its Development section.
• Where it does not: Microsoft's documentation says an AB# in a comment or in a pull request title does not create the link. A user who put it in the title and sees nothing has not found a bug.
• State words move work items. A word such as fix, fixes, fixed or a state name before the mention (Fixes AB#125, Closed AB#125) also transitions the work item, but only when the pull request merges into the default branch. With several mentions, only the first is transitioned unless each one has its own word.

Do not combine the two closures. Fixes AB#125 moves the Azure Boards work item on merge in the same way Closes #N closes a GitHub issue: neither checks the acceptance criteria. Treat it like Closes. Use the bare AB#125 (link only) while any criterion lacks evidence, and add a state word only once the evidence is recorded and the maintainer has approved the closure. The closure gate lives in github-hygiene.

Keep one source of truth for each piece of work: planning and status in Azure Boards, code and review in GitHub, the AB# mention in the description. Copying every work item into a GitHub issue gives two records that drift. Connecting the same repository to projects in more than one Azure DevOps organization can produce unexpected links, so connect it to one. Azure DevOps Server (on premises) supports GitHub Enterprise Server only; this section does not cover that setup.

Source, read 2026-10-11: Microsoft Learn, Link GitHub commits, PRs, branches, and issues to work items (page dated 2026-07-16). Re-check it before relying on a claim for a decision that is hard to undo.

Coming from Jira

Jira is not Azure DevOps, so the table above is the wrong starting point for a Jira user. Atlassian's current documentation says work item where this section says Jira issue, and space where it says Jira project; people still use both words, so accept either. The mapping below was checked against the vendor pages listed at the end on 2026-10-10. Re-check a claim before relying on it for a decision that is hard to undo; both vendors change these features.

Linking the two products. The GitHub for Atlassian app connects a GitHub Cloud organization to a Jira Cloud site: a Jira site administrator and a GitHub organization owner must both approve it. Once connected, a Jira key in a branch name, a commit message or a pull request title links that work to the Jira item, and its development panel then shows the branches, commits and pull requests (workflows and deployments can be linked too). Smart commits can also comment on an item, log time or move its status from a commit message; new repositories in a linked account have them enabled by default, and Atlassian warns that a commit can be attributed to someone other than the person who pushed it, so some organizations switch them off.

What not to promise. Atlassian's documentation describes development information flowing into Jira. It does not describe syncing GitHub issues with Jira items or carrying statuses between them, so never tell a user the two stay in step. If the team plans in Jira, keep one source of truth for each piece of work: planning and status in Jira, code and review in GitHub, with the key in the branch name and the pull request title. Mirroring every Jira item as a GitHub issue creates two records that drift. GitHub Enterprise Server connects through a separate process that this section does not cover.

The closure gate does not change: a criterion is met when its evidence is recorded, wherever the criteria live. This repository's own conventions (Refs #N, gh issue develop) assume GitHub issues; for work tracked in Jira, put the key where the tooling looks for it and the evidence in the pull request.

Sources, read 2026-10-10: Atlassian Support pages on work item keys, the work type hierarchy, statuses, priority and resolution, sprints, versions, JQL, connecting GitHub, linking development work and smart commits; GitHub Docs pages on iteration fields, sub-issues, issue types and issue search.

Setting up a repo the way you had it in ADO

Rough order, with the skill that covers each:

1. Labels (priority + category) — github-issue-first
2. Issue types, if you are in an org — github-issue-first
3. Milestones for releases, not sprints — github-releases
4. Ruleset on the default branch (required checks + review) — github-releases
5. Issue forms and PR template — github-repo-configure; CODEOWNERS and CONTRIBUTING.md — github-repo-bootstrap for a new repository, github-repo-review to audit an existing one
6. .github/release.yml for categorised release notes — github-releases
7. Projects board only if more than one maintainer — github-projects
8. Discussions enabled, with categories

Common mistakes