Workflow Issue Extraction (Step 03b)¶

Home > Reference > Workflow Issue Extraction

Reference for the issue-number extraction logic in default-workflow step 03b. This step resolves a provider-neutral tracking number from the workflow context so downstream steps can link the working branch, commit, and pull request to the correct GitHub issue, Azure Boards work item, or local tracking ID.

Contents¶

Overview
Extraction Order
Primary source: Step 03 output
Compatibility fallback: task text references
Provider Output Formats
Output Contract
Shell Security Constraints
Configuration
Examples
Troubleshooting
Related

Overview¶

Step 03b accepts the issue_creation output from step 03 plus the original task_description, then produces a canonical issue_number integer that the rest of the workflow uses.

issue_creation + task_description ──► 03b extraction ──► issue_number (int)

Step 03 is responsible for emitting a parseable tracking reference. If neither Step 03 output nor the compatibility task-text fallback is parseable, Step 03b fails loudly instead of silently continuing with the wrong branch or commit reference.

Extraction Order¶

The sources are evaluated in order; the first match wins.

Primary source: Step 03 output¶

Step 03b first parses the issue_creation value emitted by Step 03. This is the canonical source because Step 03 owns host dispatch, provider validation, reuse decisions, and create/fallback behavior.

Supported issue_creation formats:

Step 03 output	Extraction behavior
`https://github.com/owner/repo/issues/N`	Extracts `N` from `/issues/N` without a network call
`https://github.com/owner/repo/pull/N`	Uses `gh pr view` to read the first closing issue; falls back to PR number `N` if no closing issue resolves
`https://dev.azure.com/org/project/_workitems/edit/N`	Extracts `N` from `/_workitems/edit/N` without a network call
`AB#N`	Extracts `N` without a network call
`local-tracking:N`	Extracts `N` without a network call

Input:  "https://github.com/rysweet/amplihack-rs/issues/3960"
Match:  issues/3960
Output: issue_number=3960

For pull request URLs, Step 03b calls:

gh pr view <N> \
    --json closingIssuesReferences \
    --jq '.closingIssuesReferences[0].number'

The first closing issue reference is used. If the PR closes no issues or the lookup fails, the PR number itself is used as the numeric tracking ID. Step 03b does not scan task_description for GitHub issue or PR URLs.

Input:  "https://github.com/rysweet/amplihack-rs/pull/4143"
gh call: closingIssuesReferences → [3960, 3983]
Output: issue_number=3960   (first reference)

Timeout: 60 seconds. If gh does not respond within the timeout, the PR number is used as the fallback tracking ID.

Compatibility fallback: task text references¶

If issue_creation is not parseable, Step 03b falls back to references in task_description for compatibility with older or manually supplied contexts:

Task text pattern	Extraction behavior
`AB#N`	Extracts `N`
`#N`	Extracts `N`

issue_creation:   "unparseable legacy value"
task_description: "Continue work on AB#12345"
Output:           issue_number=12345

This fallback is intentionally regex-only. Step 03 is responsible for deciding whether #N means a GitHub issue, Azure Boards work item, or local reference; Step 03b only preserves the numeric workflow contract.

Provider Output Formats¶

Step 03b extracts IDs from the provider-specific output formats produced by step-03-create-issue, plus task-text fallback references used for compatibility.

Provider path	Step 03 output	Extraction result
GitHub issue	`https://github.com/owner/repo/issues/3960`	`3960`
GitHub PR fallback	`https://github.com/owner/repo/pull/4143`	First closing issue, or `4143` if none resolves
Azure DevOps work item URL	`https://dev.azure.com/org/project/_workitems/edit/12345`	`12345`
Azure Boards shorthand	`AB#12345`	`12345`
Local tracking	`local-tracking:482193`	`482193`
Compatibility Azure Boards reference	`AB#12345` in `task_description`	`12345`
Compatibility bare reference	`#12345` in `task_description`	`12345`

The AB#N shorthand is the canonical reuse output for Azure DevOps runs that start with an existing issue_number context value. It lets Step 03 reuse a known work item without requiring a live Azure CLI lookup.

Output Contract¶

After step 03b completes, the workflow context contains:

Field	Type	Description
`issue_number`	`int`	Provider-neutral tracking number extracted from step 03 output

Example output¶

{
  "issue_number": 3960
}

If extraction fails, step 03b exits non-zero and prints the unparseable issue_creation value to stderr.

Shell Security Constraints¶

Step 03b follows the same shell-security rules as the rest of the default workflow:

Constraint	Detail
Quoted variables	`ISSUE_CREATION` and `TASK_DESCRIPTION` are assigned and matched with quoted shell variables
Regex-only numeric capture	Every accepted identifier is captured with `[0-9]+`; no provider CLI receives an unvalidated ID
60-second timeout	GitHub PR closing-issue lookup uses `timeout 60`; hung subprocesses do not stall the workflow
No provider crossover	Azure Boards formats (`AB#N`, `_workitems/edit/N`) are parsed locally and do not require GitHub CLI calls
Visible failure	If no supported pattern matches, the step exits non-zero and prints the unparseable `issue_creation` value to stderr

Configuration¶

Step 03b reads the following values from the workflow context:

Context key	Required	Description
`issue_creation`	Yes	Step 03 output: GitHub URL, Azure Boards URL, `AB#N`, or `local-tracking:N`
`task_description`	Yes	Free-form string used only as a compatibility fallback source for `AB#N` or `#N` references

No environment variables are specific to step 03b. GitHub PR closing-issue lookup relies on the authenticated gh CLI configured in the user's shell. Azure Boards and local tracking extraction are regex-only.

Examples¶

Resolving from an issue URL¶

# Recipe context snippet
issue_creation: "https://github.com/rysweet/amplihack-rs/issues/3960"

issues/ match: 3960
issue_number: 3960

Resolving from a PR URL¶

issue_creation: "https://github.com/rysweet/amplihack-rs/pull/4143"

gh pr view 4143 --json closingIssuesReferences
→ [3960, 3983]
issue_number: 3960

Resolving from compatibility task text fallback¶

issue_creation: "legacy output"
task_description: "Continue work on #3983"

No supported issue_creation format → task text fallback
issue_number: 3983

Resolving from an Azure Boards shorthand¶

issue_creation: "AB#12345"
task_description: "Address review feedback for the Azure DevOps PR"

AB# match: 12345
issue_number: 12345

Resolving from local tracking¶

issue_creation: "local-tracking:482193"

local-tracking match: 482193
issue_number: 482193

Invalid step 03 output¶

issue_creation: "unparseable provider output"

No supported pattern → step 03b exits non-zero
stderr includes the unparseable issue_creation value

Troubleshooting¶

gh: command not found

Install and authenticate the GitHub CLI: gh auth login. Only GitHub PR closing-issue lookup requires gh; direct issue URLs, Azure Boards outputs, AB#N, and local-tracking:N still parse without it.

GitHub PR lookup returns no closing issues

The PR may not use closing keywords (Closes #N, Fixes #N). In that case Step 03b uses the PR number itself as the numeric tracking ID.

Task text fallback resolves a bare #N unexpectedly

Step 03b does not verify bare #N against a provider. Provider validation must happen in Step 03 before it emits issue_creation.

Task text fallback does not resolve a #N that is present

The #N pattern requires at least one digit. Values like # alone or #abc are not matched.

Multi-Provider Extraction¶

Step 03b extracts issue numbers from provider-specific URL formats in addition to GitHub issue and PR patterns:

Provider	Accepted pattern	Extraction regex
GitHub	`https://github.com/owner/repo/issues/N`	`issues/([0-9]+)`
GitHub PR	`https://github.com/owner/repo/pull/N`	`pull/([0-9]+)` plus closing-issue lookup
Azure DevOps	`https://dev.azure.com/org/project/_workitems/edit/N`	`_workitems/edit/([0-9]+)`
Azure DevOps	`AB#N`	`AB#([0-9]+)`
Local	`local-tracking:N`	`local-tracking:([0-9]+)`

The issue_number output contract is unchanged: a plain integer regardless of provider. See Multi-Provider Workflow Reference for full details.

Workflow Execution Guardrails Reference — canonical execution root and GitHub identity gate (also part of the default workflow)
How to Configure Workflow Execution Guardrails
Default Workflow — full step list
Lock Session ID Sanitization — the security fix delivered alongside this extraction improvement (PR #4143)
Multi-Provider Workflow Reference — provider detection and routing
Issues #3960 and #3983 — originating work
PR #4143 — implementation

Metadata

Field	Value
Status	Issue #718 target contract
Issues	#3960, #3983, #718
PR	#4143
Recipe file	`amplifier-bundle/recipes/default-workflow.yaml` (step `03b`)
Test file	`amplifier-bundle/tools/test_default_workflow_fixes.py`
Gadugi spec	`tests/gadugi/lock-recovery-and-issue-extraction.yaml`