azure-devops-pr-quick-create

name	azure-devops-pr-quick-create
description	Create pull requests quickly in Azure DevOps repositories using Azure CLI (`az repos pr create`) with reliable auth fallbacks. Use this skill whenever the user asks to create/open/raise a PR for Azure DevOps, especially when they mention PAT auth, `TF_VAR_devops_user_pat_163ent`, `AZURE_DEVOPS_EXT_PAT`, or sourcing `~/dotfiles/sp/163ent-devops.sp`. Prefer this skill over GitHub CLI or GitKraken tools for Azure DevOps remotes.
categories	["github"]
agents	["copilot"]
metadata	{"source":"custom","scope":"global"}

Azure DevOps PR Quick Create

Use this workflow to create PRs quickly and predictably for Azure DevOps repos.

Core rule

Use Azure CLI only for PR creation in Azure DevOps repos:

• Use az repos pr create
• Do not use GitHub CLI for Azure DevOps remotes
• Do not use GitKraken tools unless the user explicitly requests it

Input expectations

Collect or infer these values:

• Source branch
• Target branch — ask the user if not explicitly stated. Do not assume the current base branch is the right target. Default to the repo's default branch (check az repos show --query defaultBranch) only if the user has not specified one.
• PR title
• PR description/body

Work item org/project — always ask before creating a task/work item if the user has not explicitly named an org and project. The git remote org (e.g. SSC-CTO-ESLZ) is NOT necessarily the same org where work items live (e.g. Azure163ent-CloudOperations/Activities).

Fast workflow

1. Verify repo status is ready.
2. Ensure source branch exists and is pushed.
3. Authenticate Azure DevOps CLI (PAT env first, then fallback source file).
4. Create PR with az repos pr create.
5. Return PR id and web URL.

Step 0: Ensure azure-devops CLI extension is installed

Before any az repos or az boards command, verify the extension is present:

az extension show --name azure-devops &>/dev/null || az extension add --name azure-devops --yes

This is required on every machine where the extension has not been explicitly installed.

Step 1: Repo preflight

Run:

git status -sb
git rev-parse --abbrev-ref HEAD
git remote -v

Confirm:

• Correct source branch
• Branch is pushed to origin
• Remote is Azure DevOps (dev.azure.com)

If source branch is not pushed, run:

git push -u origin <source-branch>

Verify target branch exists in ADO before attempting PR creation:

az repos ref list \
  --organization "https://dev.azure.com/<org>" \
  --project "<project>" \
  --repository "<repo>" \
  --filter "heads/<target-branch>" \
  --query "[].name" -o json

If the result is [], push the target branch first:

git push origin <target-branch>

Step 2: Derive Azure DevOps metadata from origin URL

Expected remote format:

https://<optional-user>@dev.azure.com/<org>/<project>/_git/<repo>

Extract:

• Organization URL: https://dev.azure.com/<org>
• Project: <project>
• Repository: <repo>

Step 3: Authentication strategy (in order)

Try auth methods in this sequence:

1. If AZURE_DEVOPS_EXT_PAT already set, use it.
2. Else if TF_VAR_devops_user_pat_163ent is set, export it to AZURE_DEVOPS_EXT_PAT.
3. Else source credentials file and retry:

source ~/dotfiles/sp/163ent-devops.sp

Then check again for PAT env presence.

If still missing, ask user to export PAT in terminal and retry.

Step 4: Create PR

Use:

az repos pr create \
  --organization "https://dev.azure.com/<org>" \
  --project "<project>" \
  --repository "<repo>" \
  --source-branch "<source-branch>" \
  --target-branch "<target-branch>" \
  --title "<title>" \
  --description "<description>" \
  --output json

If command output is truncated or terminal closes unexpectedly, verify creation with:

az repos pr list \
  --organization "https://dev.azure.com/<org>" \
  --project "<project>" \
  --repository "<repo>" \
  --source-branch "<source-branch>" \
  --status active \
  --output json

Step 5: Return a usable PR link

From PR id <id>, build the web URL:

https://dev.azure.com/<org>/<project>/_git/<repo>/pullrequest/<id>

Always return:

• PR id
• Title
• Source -> target branch
• Web URL

Step 6 (optional): Link a work item to the PR

To look up an existing PR by ID (omit --project — it is not a valid flag for az repos pr show):

az repos pr show \
  --organization "https://dev.azure.com/<org>" \
  --id <pr-id> \
  --output json

To link a work item to a PR, use az repos pr work-item add (NOT az repos pr update --work-items):

az repos pr work-item add \
  --organization "https://dev.azure.com/<org>" \
  --id <pr-id> \
  --work-items <work-item-id> \
  --output json

To create a work item (Task) as a child of an existing Epic:

# 1. Create the Task
az boards work-item create \
  --organization "https://dev.azure.com/<org>" \
  --project "<project>" \
  --type "Task" \
  --title "<title>" \
  --description "<description>" \
  --output json

# 2. Set parent Epic (use the Task id returned above)
az boards work-item relation add \
  --organization "https://dev.azure.com/<org>" \
  --id <task-id> \
  --relation-type "parent" \
  --target-id <epic-id> \
  --output json

# 3. Link Task to PR
az repos pr work-item add \
  --organization "https://dev.azure.com/<org>" \
  --id <pr-id> \
  --work-items <task-id> \
  --output json

Copy/paste helper block

Use this helper when the user asks for a quick PR and values are already known:

set -e
az extension show --name azure-devops &>/dev/null || az extension add --name azure-devops --yes
source ~/dotfiles/sp/163ent-devops.sp || true
if [[ -z "$AZURE_DEVOPS_EXT_PAT" && -n "$TF_VAR_devops_user_pat_163ent" ]]; then
  export AZURE_DEVOPS_EXT_PAT="$TF_VAR_devops_user_pat_163ent"
fi
if [[ -z "$AZURE_DEVOPS_EXT_PAT" ]]; then
  echo "Missing Azure DevOps PAT env (AZURE_DEVOPS_EXT_PAT or TF_VAR_devops_user_pat_163ent)."
  exit 1
fi

az repos pr create \
  --organization "https://dev.azure.com/<org>" \
  --project "<project>" \
  --repository "<repo>" \
  --source-branch "<source-branch>" \
  --target-branch "<target-branch>" \
  --title "<title>" \
  --description "<description>" \
  --output json

Changing a PR's target branch after creation

az repos pr update does not support --target-branch. Use the REST API instead:

az rest \
  --method PATCH \
  --uri "https://dev.azure.com/<org>/<project>/_apis/git/repositories/<repo>/pullRequests/<pr-id>?api-version=7.1" \
  --headers "Content-Type=application/json" \
  --body '{"targetRefName": "refs/heads/<new-target>"}' \
  --resource 499b84ac-1321-427f-aa17-267ca6975798

Cross-org work item linking

az repos pr work-item add only works when the PR repo and the work item are in the same ADO org. If they are in different orgs, the link must be added manually in the PR UI.

Safety and behavior notes

• Never print PAT values in output.
• If authentication fails, report the exact blocker and next fix.
• Keep PR body concise and based on actual changed files (git status --short + git diff --name-only).
• If user asks to use Azure CLI, do not route through other PR tools.