Skip to content

Git/GitHub Integration

BMAtlassian can optionally integrate with Git and GitHub to create branches, commits, and PRs aligned with Jira stories. This is fully optional -- set git_enabled to "false" (the default) and workflows behave identically to before.

Setup

Run the discovery workflow to auto-detect your environment:

/bmad-atlassian-git-discovery

This will:

  1. Check for a git repository (offer to initialize one)
  2. Detect your GitHub remote and extract owner/repo
  3. Detect the default branch (main/master)
  4. Check gh CLI availability and authentication
  5. Check for GitHub MCP plugin
  6. Ask about Jira-GitHub integration
  7. Configure branch naming, commit format, and PR behavior
  8. Write the git_* settings to module.yaml

How It Works

Dev Story (/bmad-atlassian-dev-story)

When git is enabled, the Dev agent adds these steps to its workflow:

  1. Create branch -- {project_key}-{number}/{kebab-summary} (e.g., PROJ-42/add-user-auth)
  2. Commit & push -- stages all changes, commits with issue key prefix (e.g., feat(PROJ-42): implement auth endpoint)
  3. Create PR -- pushes and opens a draft PR linking back to the Jira issue

Branch names include the Jira issue key, enabling automatic linking via the Jira-GitHub integration.

Code Review (/bmad-atlassian-code-review)

When git is enabled, the QA agent adds these steps:

  1. Load PR diff -- fetches the PR diff for additional review surface
  2. Approve PR -- submits an approval review if code review passes
  3. Request changes -- submits a changes-requested review if code review fails

Re-work Cycle

If a review fails and Dev picks up the story again:

  1. The existing branch is checked out (not recreated)
  2. New commits are added to the same branch
  3. The existing PR is updated automatically (no new PR created)

Configuration

Variable Description Default
git_enabled Enable/disable all git operations "false"
git_github_repo GitHub repo (owner/repo) ""
git_default_branch Base branch for new feature branches "main"
git_branch_prefix Branch name prefix "{jira_project_key}"
git_commit_prefix Commit message prefix "feat({issue_key})"
git_auto_push Auto-push commits to remote "true"
git_auto_pr Auto-create PR on Review transition "true"
git_pr_draft Create PRs as drafts "true"
git_pr_auto_approve Auto-approve PR on review pass "true"
git_pr_auto_merge Auto-merge PR on approval "false"

Tool Precedence

Git operations use this fallback chain:

  1. GitHub MCP plugin (if available)
  2. gh CLI (if installed and authenticated)
  3. Raw git (always available)

Fault Tolerance

Git failures never block Jira operations. If a git operation fails (network error, auth issue, missing tool), the error is logged and the workflow continues with all Jira operations intact.

Disable at any time

Set git_enabled: "false" in module.yaml to instantly disable all git operations. Workflows revert to Jira-only behavior.

Jira-GitHub Auto-Linking

If you have the GitHub for Jira integration installed on your Atlassian site, branch names containing Jira issue keys will automatically link commits, branches, and PRs to the corresponding Jira issue.