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). hcl accelerate vsm with github and jira
  2. The integration name for this workbook should be “JKE GitHub App1”. hcl accelerate vsm with github and jira
  3. The GitHub URL should be the URL to the repository (plugin version 1.0.31 and later do not require this) hcl accelerate vsm with github and jira
  4. We can get the “Name” (repository name) and “Owner” (repository account) fields from the GitHub repository URL. hcl accelerate vsm with github and jira
  5. The API URL depends on your instance of GitHub. This workbook assumes a public instance of GitHub which uses “https://api.github.com”. hcl accelerate vsm with github and jira
  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. hcl accelerate vsm with github and jira
  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) hcl accelerate vsm with github and jira
  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). hcl accelerate vsm with github and jira
  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. hcl accelerate vsm with github and jira
    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. hcl accelerate vsm with github and jirahcl accelerate vsm with github and jira

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. hcl accelerate vsm with github and jira

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. hcl accelerate vsm with github and jira

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.

hcl accelerate vsm with github and jira

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. hcl accelerate vsm with github and jira
  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. hcl accelerate vsm with github and jira
  3. Commit the changes to a separate branch. The commit message and branch name can be whatever you want. hcl accelerate vsm with github and jira
  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”. hcl accelerate vsm with github and jira
  5. Confirm that the pull request is open and contains the Jira card’s ID. hcl accelerate vsm with github and jira
  6. After waiting for HCL Accelerate to detect and update, the dot should appear in the “In Progress” stage. hcl accelerate vsm with github and jira

4.2 Move the Dot to “In Review”

  1. Update the Jira card to “In Review”. hcl accelerate vsm with github and jira
  2. Wait for HCL Accelerate to update. The dot should move from “In Progress” to “In Review”. hcl accelerate vsm with github and jira

4.3 Move the Dot to “Merged”

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

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.

Comment wrap
Further Reading
article-img
Secure DevOps | June 9, 2022
Introducing HCL Accelerate v3.1
HCL Accelerate is continuing to see significant Value Stream Management adoption! With the release of HCL Accelerate 3.1, we brought significant features and performance improvements for our largest customers. If you are not far in your VSM journey, see below for some new onboarding features and guidance.
article-img
Secure DevOps | May 19, 2022
Accelerate on Kubernetes: Or, How I Learned to Stop Worrying and Love Automated Container Orchestration
Containerization is everywhere these days, and technologists are scrambling to adopt it in their organizations. But what exactly is it? Is it actually beneficial, or just a fad? What's the best way to leverage it? And most importantly, how does it relate to HCL Accelerate?
article-img
Secure DevOps | April 25, 2022
OpenShift Installation Updates
Starting from HCL Accelerate version 3.1.0, OpenShift Template installation will be removed. If you are an OpenShift user, do not worry, we will continue supporting OpenShift platforms through Helm charts.
Close
Filters result by
Sort:
|