HCL Accelerate VSM with GitHub and Jira

This tutorial shows how to create a GitHub integration in HCL Accelerate. It is the second part of a tutorial series on configuring and using an HCL Accelerate value stream with Jira, GitHub, and Jenkins. Some value stream steps assume completion of the Jira tutorial. If you have not completed the Jira tutorial, you can do so now here.

1. Setup a GitHub repository

GitHub requirements:

• Access to a GitHub repository (this workbook assumes a public repository)
• GitHub API token
• Ability to create a pull request (PR).

This workbook assumes a public GitHub account and public repository. If you do not have a public GitHub account, you will need to create one, as well as a public repository. The repository contents do not matter, but a PR is required and must contain the issue ID of the Jira issue we are following in the PR name (the example here is “JKET-1”).

2. Create a GitHub Integration

Note: The GitHub plugin configuration changed with version 1.0.31. For version 1.0.31 and later, the URL field is not required; however, a user access key is required as mentioned in step 9 below.

1. The integration can be added from the plugins page in HCL Accelerate (Settings>Integrations>Plugins).
2. The integration name for this workbook should be “JKE GitHub App1”.
3. The GitHub URL should be the URL to the repository (plugin version 1.0.31 and later do not require this)
4. We can get the “Name” (repository name) and “Owner” (repository account) fields from the GitHub repository URL.
5. The API URL depends on your instance of GitHub. This workbook assumes a public instance of GitHub which uses “https://api.github.com”.
6. Create a GitHub personal access token for an account with access to the repository, then copy and paste the token to the integration form. Public GitHub tokens can be created at https://github.com/settings/tokens. There is no need to select check-boxes for scoping/privileges when creating the token.
7. Click the “Add” button to create the integration. Navigate to the “Integrations” view to verify that the integration was created and is “Online”. You can inspect integration details by expanded a dropdown. (Note that the Jira integration shown below was created as part of a separate exercise)
8. A blue dot beside the integration names indicates that an upgrade is available. It’s a good idea to upgrade the plugin at this point. Click on “Upgrade” under the three-vertical dot (kabob) menu. The plugin image should update to the latest version (1.0.36 or later).
9. User Access Key (GitHub Plugin Version 1.0.31 and Later:
   1. An HCL Accelerate user access key is required for the GitHub plugin version 1.0.31 and later. The URL field is also removed. Any update from a version older than 1.0.31 will require editing the integration with a user access key.
   2. To create an access key, go to “Settings” > “My profile” and click “Create”. It’s a good idea to name your access key according to the integration that will use it, so name it something like “JKE GitHub App1”. Make sure to copy the key at this point, since you will not be able to copy it later.
   3. After creating a key, navigate back to the integrations page. Click “Edit” from the kabob menu for the GitHub integration. Provide the user access key in the form. Also verify the remaining fields and provide any values such as repositories as needed.

3. Adding the GitHub Integration to a value stream

Use the vsm.json file to add the GitHub integration and a linkRule to the value stream. Download the file and then modify it by adding the following sections, then upload the file again to apply changes. The work item (dot) should move to the “In Progress” stage since the PR is open. Note that if a PR or commit is not properly linked to a work item, it will show up as either a square (PR) or triangle (commit), whereas a dot represents an actual work item including all linked PRs and commits. You can link multiple PRs to a single work item. Commits to a PR branch will update the work item.

NOTE: From this point forward, some steps assume prior completion of the VSM with Jira tutorial. If you have not finished that tutorial yet, feel free to complete it now, or proceed without a Jira integration. GitHub can be integrated and show PRs and commits perfectly fine in a value stream on its own. However, there will be no work item linking without an issue tracker integration and corresponding link rule, and you will need to configure a value stream. In addition to editing the vsm.json file to include a GitHub integration as mentioned below, you will also need to edit stage queries, for example: "query":"pr.status=open".

1. Download the working vsm.json file from the value stream.

2. Add the GitHub integration to the .json content.

Similar to the json used in a separate tutorial to add a Jira integration, we will need to add another json object to the integrations array. The name here must match the GitHub integration name created earlier. We only need to add the GitHub object with its single name property for now. If the vsm.json contains other integrations like Jira, we can ignore them.

"integrations": [
 {
  "name":"JKE GitHub App1"
 }
 //other integrations…
],

3. Add a GitHub-Jira linkRule to the vsm.json configuration.

replace the empty link rules array…

"linkRules": [],

with an array that contains a new link rule object. This linkRule links GitHub PRs to Jira issues based on a regex pattern that recognizes a jira.id within a pr.name.

"linkRules": [
 {
  "fromIntegrationName": "JKE GitHub App1",
  "toIntegrationName": "JKE Jira 1",
  "fromField": "pr.name",
  "toField": "issue.id",
  "pattern": "([A-Z]+-[0-9]+)"
 }
],

4. Save and upload the vsm.json file.

Seeing Squares?

Depending on your GitHub activity, you may notice a few squares in a stage like “Merged”. These represent prior commits that are not linked to Jira cards. If you see such squares you can ignore them since we will be focusing on creating a new PR and linking it to a Jira card.

4. Stage changes using Jira and GitHub

Now that we setup GitHub as an integration, it’s time to see it in action in a value stream. GitHub can be used as a standalone integration or alongside many different integrations. Recall that, in this case, we are using the VSM from the Jira tutorial, so the example here is with Jira.

4.1 Move the Dot to “In Progress” (Create a PR)

In order to move our dot to the “In Progress” stage, we need to create a pull request (PR) in GitHub.

1. Edit any file in the repository. This example just edits a README file that can be edited by clicking on the pencil icon to the upper right of the file.
2. Make changes to the file. Think of these changes as corresponding to the Jira card created earlier. This represents the code changes for that card.
3. Commit the changes to a separate branch. The commit message and branch name can be whatever you want.
4. When prompted to create a pull request, provide the Jira card’s ID/code in the pull request name (ex. “JKET-1”), then click “Create pull request”.
5. Confirm that the pull request is open and contains the Jira card’s ID.
6. After waiting for HCL Accelerate to detect and update, the dot should appear in the “In Progress” stage.

4.2 Move the Dot to “In Review”

1. Update the Jira card to “In Review”.
2. Wait for HCL Accelerate to update. The dot should move from “In Progress” to “In Review”.

4.3 Move the Dot to “Merged”

1. Go ahead and merge the PR in GitHub.
2. Wait for HCL Accelerate to update. The dot should move from “In Review” to “Merged”.

Next Steps: From Development to Build servers and Beyond

Wow! We’re seeing both Jira and GitHub activity coming together to a single source of truth in HCL Accelerate. Our next step will be to integrate builds and deployments to track our work item all the way into production. To do that, we will need to create a Jenkins integration.