osowskit / jira-link-updater

GitHub App that replaces JIRA IDs in Issue comments with a URL to the JIRA issue

Overview

Ever add a JIRA ticket id to an Issue or Pull Request and wish it would link directly to the ticket. This GitHub App replaces JIRA IDs in comments with a URL to the JIRA issue. 🎉

End User Instructions

Instructions to configure GitHub.com repositories.

1. Visit jira-link-updater app and grant it access to your repositories.
2. Add a configuration file to each repository to set a path to your JIRA instance.
   • Filename: JIRA_SETTINGS.yaml
   • Example:

   jira_hostname: "https://[SERVERNAME].atlassian.net"
   

3. New Pull Requests and Issue comments with the format [XYZ-123] will be replaced with a hyperlink to the JIRA issue.

GitHub Enterprise Instructions

1. Set up a new GitHub App on your GitHub Enterprise +2.12 instance.
   • Issues permissions - Read and Write
   • Pull requests permissions - Read and Write
   • Subscribe to events
     • Issues
     • Pull request event subscription
     • Issue Comments
2. Host this application on a network that allows traffic to/from the GitHub Enterprise instance. ruby server.rb
3. Install the App and grant it access to your repositories.
4. Add comments to Issues and Pull Requests in the format [XYZ-123] to be replaced with a hyperlink

jira-link-updater's Issues

Handle Webhooks at Scale

Problem

Very active repositories may eventually time out with serial processing of webhooks. GitHub may also be temporarily unavailable so handle retrying.

Discussion

• Store webhook events and process them separately.
• Gracefully fail when GitHub's API is unavailable
• Cache the jira URL instead of loading it each webhook

Replace multiple matches

Handle multiple occurrences of matching JIRA IDs in a comment.

Allow comment edits to trigger link replacement

The source currently ignores issue_comment : updated events to naively avoid processing this integration updating a comment

jira-link-updater/server.rb

Lines 93 to 94 in 3044034

	# Ignore Updated or Deleted comments
	if webhook_action == "opened"

The webhook payload will contain returns a sender:type:Bot that can be checked to ignore an update by this integration. However, for a user update - this may not prevent the app attempting to nest the link.

Gracefully handle both .com and Enterprise

This app was written to assume GitHub Enterprise instance with a single JIRA url. This limits installations for both companies with multiple JIRA instances and .com users.

• Handle API calls for both GHE and .com
• #7 load JIRA hostname per repository
• Consider queuing webhook events and processing them later

Load Atlassian JIRA hostname

Don't hardcode path to Atlassian JIRA server. This should be configurable from YAML or Environment Variables.

jira-link-updater/server.rb

Line 66 in 26b7388

jira_link = "[#{match}](https://osowskit.atlassian.net/browse/#{jira_id})"

Handle matches in Issue `body`

Handle pull_request created event and replace matches in body

Consider replacing ID in the title hyperlinks in title don't show up so can be ignored

Load JIRA hostname from repository file

Problem

Loading the JIRA_HOSTNAME from an environment variable ties a single running app to one url. This limits allowing multiple JIRA instances - either on an internal network or for supporting github.com.

Requirements

• Define YAML file that needs to exist in each repository
• Modify App permissions to read a single file
• Modify App to read and use this information
• Determine how to cache JIRA URLs
  • Reading this file for each webhook can have serious performance implications

Handle missing JIRA URL

Problem

#7 requires that the JIRA fqdn is stored in a YAML file.

Discussion

It is possible to create an issue in each repository that can't load a JIRA URL stating jira-link-updater GitHub App requires the YAML file, displays a warning if the YAML is malformed, and possibly creates the YAML file as a template.