JIRA Cheatsheet - TISTATechnologies/caseflow GitHub Wiki

Below are results from experimenting with our Jira's GitHub integration and Smart Commits.

Enable Smart Commits from your GitHub account

Our Jira uses your va.gov email addresses to recognize you as a user who can edit Jira tickets. This means your git commit messages must have that email address for the Smart Commit to work.

  1. Check your email address: in your caseflow directory, run git config user.email
  2. If needed, updated it: git config user.email "[email protected]" or edit .git/config (more details)
  3. Uncheck "Keep my email addresses private" in your GitHub account settings (Settings > Email). This is explained in the "gotchas" below.

Using Smart Commit commands

Things you can do with Smart Commit

  • comment on issues (using #comment)
  • transition issues to any status defined in the project's workflow
  • (irrelevant) record time tracking information against issues

Smart Commit operates on all git branches, not just the main master branch. Although it seems a GitHub pull request is needed for Jira to see the commit messages(?)

Example workflow

Given a Jira ticket workflow like this:

we can update the Jira ticket status and add comments without going to Jira:

  1. Create your feature branch (and eventually a GitHub PR) to work on Jira ticket CASEFLOW-106
  2. Update Jira ticket's status to "IN PROGRESS" and also add a comment: git commit --allow-empty -m "CASEFLOW-106 #in-progress #comment Starting on this ticket"
    • The --allow-empty argument enables creating a git commit without any file changes.
    • Regarding the workflow transition name in-progress, process-issues-with-smart-commits states: "The Smart Commit only considers the part of a transition name before the first space. So, for a transition name such as finish work, then specifying #finish is sufficient. You must use hyphens to replace spaces when ambiguity can arise over transition names, for example: #finish-work".
    • Gotcha: The transition name in the commit message must match the label in the Workflow dropdown of the Jira ticket. For example, if the dropdown shows a "Start Work" option, the commit message must include #start-work even though the desired status name is "In Progress".
    • TODO: If we set up a trigger, then the assignee could be automatically updated to the commenter.
  3. git push your latest branch so that Jira can know about the latest commit.
  4. Create a GitHub pull request
  5. If desired, add a Jira comment with a link to the PR: git commit --allow-empty -m "CASEFLOW-106 #comment Associated PR: https://github.com/department-of-veterans-affairs/caseflow/pull/15631". Note there should already be a link to the PR in Jira's "Development" sidebar.
    • It could take about 30 minutes for Jira to recognize the commit messages and update the "Development" sidebar, which shows the commits that contain the Jira ticket ID, along with branches and PRs associated with the commit messages:
    • Unlike GitHub, you'll have to refresh your browser to get updates to the Jira page.
  6. git push your latest branch so that Jira can know about the latest commit.
  7. git commit --allow-empty -m "CASEFLOW-106 #in-code-review PR is ready for review"
  8. git push your latest branch so that Jira can know about the latest commit.

Automation

You could write a script that does something like the following:

JIRA_TICKET=CASEFLOW-106
BRANCH_SUFFIX=my-cool-feature

git checkout -b ${JIRA_TICKET#*-}-${BRANCH_SUFFIX}
git commit --allow-empty -m "${JIRA_TICKET} #in-progress #comment Starting on this ticket"
git push

# Use gh CLI tool (https://github.com/cli/cli) to create a PR
gh pr create --web --title "${JIRA_TICKET} #done ${BRANCH_SUFFIX} [${JIRA_TICKET}](https://vajira.max.gov/browse/${JIRA_TICKET})"
# Then, manually edit the PR title and description in the browser.

Once the PR is ready for review:

git commit --allow-empty -m "${JIRA_TICKET} #in-code-review PR is ready for review"
git push

Closing the Jira ticket automatically once PR merges

If you title your PR with something like "CASEFLOW-106 #done Allow CAVC Litigation Support Users to Correct Issues", then once the PR is merged by GitHub, Jira will recognize the Smart Commit message and update the status of the Jira ticket:

and the PR shows as "MERGED":

  • Gotcha: Because the PR merge is done by GitHub using your primary email address of your GitHub account, you'll have to make your va.gov email as your primary email and uncheck "Keep my email addresses private" in your GitHub account settings (Settings > Email).
  • GitHub notifications can still go to another email address (Settings > Notifications > Email notification preferences)
  • Why this works: Jira is not aware of Smart Commit commands in the PR's title until the PR is actually merged (and a corresponding commit is created).

Getting email notifications from Jira

If you want more immediate email notifications from Jira, create an auto-forward rule in Outlook for your va.gov email account.

On Jira's website

  • Quickly navigate and edit a field - If you want to edit a single field of the ticket without clicking edit and scrolling, hit . , start to type out the field, hit enter, and type in your value!

See more keyboard shortcuts here: https://jira.atlassian.com/secure/ViewKeyboardShortcuts!default.jspa

⚠️ **GitHub.com Fallback** ⚠️