|
| 1 | +# Bridge: Jira-to-GitHub Issue Workflow |
| 2 | + |
| 3 | +Create GitHub Issues from Jira tickets so fullsend agents can pick them up and |
| 4 | +implement them. This is the second step after `groom` — it assumes the ticket |
| 5 | +is already agent-ready (score 10+ on the readiness rubric). |
| 6 | + |
| 7 | +Three things happen: |
| 8 | + |
| 9 | +1. Read the Jira ticket and extract structured information |
| 10 | +2. Create a GitHub Issue with fullsend-compatible formatting |
| 11 | +3. Link both sides (Jira comment with GH link, GH issue body with Jira link) |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +``` |
| 16 | +/fullsend bridge <KEY> # Bridge to auto-detected repo |
| 17 | +/fullsend bridge <KEY> --repo owner/name # Bridge to specific repo |
| 18 | +/fullsend bridge <KEY> --dry-run # Preview, no mutations |
| 19 | +/fullsend bridge --batch <JQL> --repo owner/name # Bridge multiple tickets |
| 20 | +``` |
| 21 | + |
| 22 | +## Workflow |
| 23 | + |
| 24 | +### Step 1 — Fetch and Validate the Jira Ticket |
| 25 | + |
| 26 | +```bash |
| 27 | +acli jira workitem view <KEY> --json |
| 28 | +``` |
| 29 | + |
| 30 | +Fall back to `jira issue view <KEY>` if acli is unavailable. |
| 31 | + |
| 32 | +**Validate agent-readiness**: Run a quick score against the groom rubric |
| 33 | +(see `references/groom.md`). If score < 7: |
| 34 | + |
| 35 | +> "This ticket scores {score}/12 on agent-readiness. Run `/fullsend groom <KEY>` |
| 36 | +> first to improve it, or proceed anyway? [groom/proceed/cancel]" |
| 37 | +
|
| 38 | +If score is 7–9, note the weak dimensions but proceed. |
| 39 | + |
| 40 | +### Step 2 — Detect Target Repository |
| 41 | + |
| 42 | +Resolution order: |
| 43 | + |
| 44 | +1. **`--repo` flag**: Use as-is. |
| 45 | +2. **`repo:` label on Jira ticket**: Extract repo name, map to full `owner/name` |
| 46 | + using `references/repo-mapping.md`. |
| 47 | +3. **Component field**: Map Jira component to a repo using `references/repo-mapping.md`. |
| 48 | +4. **Ask the user**: Present known repos from the mapping file, let them pick. |
| 49 | + |
| 50 | +Verify the repo exists and the user has access: |
| 51 | + |
| 52 | +```bash |
| 53 | +gh repo view <owner/name> --json name,owner |
| 54 | +``` |
| 55 | + |
| 56 | +### Step 3 — Check for Existing GitHub Issues |
| 57 | + |
| 58 | +Search for duplicates before creating: |
| 59 | + |
| 60 | +```bash |
| 61 | +gh issue list --repo <owner/name> --state open --search "<jira key OR summary keywords>" |
| 62 | +``` |
| 63 | + |
| 64 | +If a match exists: |
| 65 | + |
| 66 | +> "Found existing issue #N: 'title'. Is this the same work? [skip/link/create-anyway]" |
| 67 | +
|
| 68 | +- **skip**: Don't create. Optionally add Jira link to existing issue. |
| 69 | +- **link**: Link Jira ticket to existing issue (comment on both sides). Done. |
| 70 | +- **create-anyway**: Proceed with new issue. |
| 71 | + |
| 72 | +Also check Jira comments for existing "Bridged to GitHub" links. If found, ask |
| 73 | +before creating a second issue. |
| 74 | + |
| 75 | +### Step 4 — Create the GitHub Issue |
| 76 | + |
| 77 | +Build the issue using the template below. |
| 78 | + |
| 79 | +```bash |
| 80 | +gh issue create --repo <owner/name> \ |
| 81 | + --title "<title>" \ |
| 82 | + --label "fullsend" \ |
| 83 | + --body "$(cat <<'EOF' |
| 84 | +<body> |
| 85 | +EOF |
| 86 | +)" |
| 87 | +``` |
| 88 | + |
| 89 | +**Labels**: Always add `fullsend`. Add additional labels based on ticket type: |
| 90 | + |
| 91 | +| Jira type | GitHub labels | |
| 92 | +|-----------|--------------| |
| 93 | +| Bug | `fullsend`, `bug` | |
| 94 | +| Story/Task | `fullsend`, `enhancement` | |
| 95 | +| Vulnerability/CVE | `fullsend`, `security` | |
| 96 | +| Investigation (`needs-investigation`) | `fullsend`, `needs-investigation` | |
| 97 | + |
| 98 | +### Step 5 — Link Both Sides |
| 99 | + |
| 100 | +**On Jira** — add a comment: |
| 101 | + |
| 102 | +```bash |
| 103 | +acli jira workitem comment --key <KEY> --comment "Bridged to GitHub: <issue-url>" --yes |
| 104 | +``` |
| 105 | + |
| 106 | +**On GitHub** — the Jira link is already in the issue body (from the template). |
| 107 | + |
| 108 | +### Step 6 — Report |
| 109 | + |
| 110 | +```markdown |
| 111 | +Bridged: <JIRA-KEY> → <owner/name>#<number> |
| 112 | + Jira: https://redhat.atlassian.net/browse/<KEY> |
| 113 | + GitHub: <issue-url> |
| 114 | + Score: <readiness-score>/12 |
| 115 | +``` |
| 116 | + |
| 117 | +--- |
| 118 | + |
| 119 | +## GitHub Issue Template |
| 120 | + |
| 121 | +```markdown |
| 122 | +## Problem |
| 123 | + |
| 124 | +{problem_description} |
| 125 | + |
| 126 | +## Context |
| 127 | + |
| 128 | +{context} |
| 129 | + |
| 130 | +**Jira ticket**: [{jira_key}]({jira_url}) |
| 131 | +**Type**: {issue_type} |
| 132 | +**Priority**: {priority} |
| 133 | + |
| 134 | +## Location |
| 135 | + |
| 136 | +{location_hints} |
| 137 | + |
| 138 | +## Acceptance Criteria |
| 139 | + |
| 140 | +{acceptance_criteria} |
| 141 | + |
| 142 | +## Notes for the Agent |
| 143 | + |
| 144 | +{agent_notes} |
| 145 | + |
| 146 | +--- |
| 147 | +*Bridged from Jira by `/fullsend bridge`* |
| 148 | +``` |
| 149 | + |
| 150 | +### Field Mapping |
| 151 | + |
| 152 | +How to populate each section from the Jira ticket: |
| 153 | + |
| 154 | +| Template section | Jira source | Fallback | |
| 155 | +|-----------------|-------------|----------| |
| 156 | +| `problem_description` | Description — extract "Problem" or "Current vs Expected" section | Full description if unstructured | |
| 157 | +| `context` | Description — extract "Context" section, plus linked issues | Summary + priority as minimal context | |
| 158 | +| `jira_key` | Issue key (e.g., RHIDP-1234) | — | |
| 159 | +| `jira_url` | `https://redhat.atlassian.net/browse/{key}` | Use `issues.redhat.com` if JQL source differs | |
| 160 | +| `issue_type` | Issue type field (Bug, Story, Task, etc.) | — | |
| 161 | +| `priority` | Priority field | "Undefined" if not set | |
| 162 | +| `location_hints` | Description — extract "Location" section, or `repo:` labels, or component field | Omit section if no location info | |
| 163 | +| `acceptance_criteria` | Description — extract "Acceptance Criteria" section | Omit section if none | |
| 164 | +| `agent_notes` | Description — extract "Notes for the Agent" section, plus any agent-relevant comments | Omit section if none | |
| 165 | + |
| 166 | +### Title Rules |
| 167 | + |
| 168 | +- Use the Jira summary as the GitHub Issue title |
| 169 | +- If the Jira summary is too vague, prepend the type: `fix: {summary}`, `feat: {summary}` |
| 170 | +- Keep under 80 characters |
| 171 | +- Don't include the Jira key in the title (it's in the body) |
| 172 | + |
| 173 | +### Label Mapping |
| 174 | + |
| 175 | +| Condition | Labels to add | |
| 176 | +|-----------|--------------| |
| 177 | +| Always | `fullsend` | |
| 178 | +| Jira type = Bug | `bug` | |
| 179 | +| Jira type = Story or Task | `enhancement` | |
| 180 | +| Jira type = Vulnerability | `security` | |
| 181 | +| Jira label `needs-investigation` | `needs-investigation` | |
| 182 | +| Jira priority = Blocker or Critical | `priority/critical` | |
| 183 | + |
| 184 | +### Idempotency |
| 185 | + |
| 186 | +Before creating, check if the issue already exists: |
| 187 | + |
| 188 | +1. Search for `{jira_key}` in open issues (the Jira link in the body makes this searchable) |
| 189 | +2. If found, report "Already bridged" with the existing issue URL |
| 190 | +3. If the user wants to re-bridge (ticket was updated), close the old issue with a comment and create a new one |
| 191 | + |
| 192 | +--- |
| 193 | + |
| 194 | +## Batch Mode |
| 195 | + |
| 196 | +When bridging multiple tickets (`--batch`): |
| 197 | + |
| 198 | +1. Fetch all matching Jira tickets |
| 199 | +2. Score each against agent-readiness |
| 200 | +3. Present a summary table: |
| 201 | + |
| 202 | +```markdown |
| 203 | +| # | Jira Key | Summary | Score | Target Repo | Action | |
| 204 | +|---|----------|---------|-------|-------------|--------| |
| 205 | +| 1 | RHIDP-123 | Fix auth redirect | 11/12 | owner/repo | Bridge | |
| 206 | +| 2 | RHIDP-456 | Update notification | 6/12 | owner/repo | Needs grooming | |
| 207 | +| 3 | RHIDP-789 | Add dark mode | 10/12 | owner/repo | Bridge | |
| 208 | +``` |
| 209 | + |
| 210 | +4. Ask: "Bridge {n} ready tickets? [y/N]" |
| 211 | +5. Create issues sequentially, report each URL |
| 212 | + |
| 213 | +--- |
| 214 | + |
| 215 | +## Error Handling |
| 216 | + |
| 217 | +| Error | Action | |
| 218 | +|-------|--------| |
| 219 | +| Jira ticket not found | "Ticket <KEY> not found." | |
| 220 | +| Target repo not found | "Repository <owner/name> not found or no access." | |
| 221 | +| `gh issue create` fails | Show error. Common cause: missing labels (create them first). | |
| 222 | +| No repo detected | Ask user to specify with `--repo`. | |
| 223 | +| Ticket already bridged | Check Jira comments for existing "Bridged to GitHub" link. Ask before creating a second issue. | |
0 commit comments