Jira Cloud GitHub: Leveraging GitHub TaskLists to emulate the Epic-Child relationship from Jira

Jira allows you to create complex hierarchy between issues to better organize your project. However, if you are syncing such a Jira project to GitHub, chances are you would want to maintain some semblance of this hierarchy on the GitHub side as well. The only effective way we found to do this was by using Task Lists in GitHub. Once you get a hang of how these TaskLists work, you can build complex hierarchical structures even in GitHub!

Use Case

The use case being discussed here would be syncing Jira issues to GitHub issues with the following requirements:

Ticket gets created in Jira
Dynamically create the GitHub issue in the correct repository based on the user selection from a custom field in Jira.
Represent the Epic-Child relationship from Jira to GitHub using TaskLists.
Maintain the bi-directional synchronization between issues.
When a GitHub issue is Closed, mark the Jira ticket as Done.

Solution

Step 1: Set up Trigger on Jira side.

Create a Jira trigger based on the drop down custom field and the Jira project:
Jira Trigger
```
project=CM and "GitHub Repository" != null
```

Step 2: Determine the target repository in GitHub based on user selection from Jira side.

From the Jira side, we need to ensure that the custom field value is being sent out. This can be done by adding the following line in the outgoing script of Jira:
Jira Outgoing
```
replica.customFields."GitHub Repository" = issue.customFields."GitHub Repository"
```

Now on the GitHub side, we decide which repository to create the issue in. Add the following in the GitHub Incoming script:

GitHub Incoming

if(firstSync){
    if (replica.customFields."GitHub Repository"?.value?.value == "Project Mars")
        issue.repository   = "majid-org/project-mars"
    else if (replica.customFields."GitHub Repository"?.value?.value == "Demo Repo")
        issue.repository   = "majid-org/demo-repo"
    issue.summary      = replica.summary


}

Step 3: If Jira is sending an Epic, add the child issues to the replica.

We use the JiraClient to run an API call to run a JQL filter and gather the results into the replica."child" data structure:

Jira Outgoing

replica."child" = []
if (issue.issueType.name == "Epic"){
    def js = new groovy.json.JsonSlurper()
    def jql = "cf[10014]=${issue.key}".toString()
    def localIssue = new JiraClient(httpClient).http("GET", "/rest/api/latest/search", ["jql":[jql]], null, [:])  { 
        response ->
        if (response.code >= 300 && response.code != 404) 
            throw new com.exalate.api.exception.IssueTrackerException("Failed to perform the request GET")         
        if (response.code == 404) 
            return null
        def txt = response.body as String
        txt = js.parseText(txt)
        txt.issues.each {
            it ->
            replica."child" += it.id 
        }
    }
}

Step 4: Add TaskLists to the GitHub issues based on whether an Epic has arrived or a child issue.

We extract the data from the replica."child" data structure and add the relevant task lists:

GitHub Incoming

issue.description  = replica.description
if (replica.issueType.name != "Task"){
    if (replica?."child".size != 0){
        issue.description += "\n\n______\nRelated Issues\n______"
        replica."child".each{
            it ->
            def localParent = syncHelper.getLocalKeyFromRemoteId(it, "issue")?.key
            issue.description += "\n- [ ] #${localParent}"
        }
    }
}


if (replica.issueType.name == "Task"){
    if (replica?.parentId){
        issue.description += "\n\n______\nParent Issue\n______"
            def localParent = syncHelper.getLocalKeyFromRemoteId(replica.parentId, "issue")?.key
            issue.description += "\n- [ ] #${localParent}"
        }
}

Step 5: Icing on the cake!

When a child ticket in Jira is Exalated, this creates a sync event for the parent (Epic) before the child has been created in GitHub.
The result is that the Task List contains a null in GitHub on firstSync.

To get around this, we add store(issue) and syncBackAfterProcessing() to the firstSync block in GitHub. This ensures that the child sends a syncBack to Jira:

GitHub Incoming

if(firstSync){
    if (replica.customFields."GitHub Repository"?.value?.value == "Project Mars")
        issue.repository   = "majid-org/project-mars"
    else
        issue.repository   = "majid-org/demo-repo"
    issue.summary      = replica.summary
    issue.description  = replica.description
    store(issue)
    syncHelper.syncBackAfterProcessing()
}

Then in Jira, we use the following to send a syncEvent for the parent (Epic):

Jira Incoming

if(issue.typeName == "Task"){
    def a = ""
    def matcher  = replica.description =~ /#(\d{1,3})$/
    if (matcher)
        a = replica.description.split("#")[1]
   
    def localIssue = syncHelper.getLocalIssueKeyFromRemoteId(issue.'SNOW Company'.toLong())
    def res = httpClient.get("/rest/api/3/issue/${localIssue.urn}")
    res = httpClient.get("/rest/api/3/issue/${res.fields.parent.key}")
    def localParent = syncHelper.getLocalIssueKeyFromRemoteId(res.fields.customfield_10094.toLong())

   syncHelper.eventSchedulerNotificationService.scheduleSyncEventNoChangeCheck(connection, localParent)
}

Step 6: Status sync from GitHub to Jira

Add the following status mapping on the Jira side to ensure that if GitHub issues are closed, the corresponding Jira tickets get closed too:
Jira Incoming
```
def statusMapping = ["open":"To Do", "closed":"Done"]
def remoteStatusName = replica.status.name
issue.setStatus(statusMapping[remoteStatusName])
```