Lesson 3 Integrating GitHub into a value stream

Provide GitHub repository data to the value stream.

Before you begin

Before you begin this lesson, make sure that you complete the previous lesson.

To complete this lesson, you need a GitHub personal access token.

About this task

In this lesson you integrate a Git repo into the tutorial value stream.

To modify the tutorial value stream, complete the following steps:

Procedure

  1. Click Settings > Integrations > Plugins.
  2. On the Plugins tab, click Add Integration for the GitHub plug-in.
    Integrations can be defined in several ways. You can define them directly in the value stream's JSON file "integrations" array. You can also define an integration on the Plug-in page, and then reference it in the JSON file. In this lesson, we configure the integration on the Plug-in page. In a later lesson, we will associate the GitHub integration to the tutorial value stream.
  3. On the Add GitHub integration window, configure an integration by completing the following steps:
    1. In the Integration Name field, enter a name for the integration, such as "Git tutorial."
      Later, we use this name to associate the integration to our value stream.
    2. In the Url field, enter the URL for the GitHub project that you configured earlier.
      The URL is similar to this example, https://github.com/myGitHubID/myGitHubProject.
    3. In the Name field, enter the name of the GitHub repository.
      Using the example URL from the preceding step, the name is myGitHubProject.
    4. In the Owner field, enter the GitHub account that owns the repository.
      Using the example URL, the owner is myGitHubID.
    5. In the Token field, enter your GitHub personal access token.
    6. In the API URL field, enter the GitHub API URL.
      For example, https://api.github.com.
    7. Click Add.
    The integration is listed on the Integrations page. If the integration is successful, the Status field displays Online. If the status is not Online, use the View log option to troubleshoot the integration. You can increase the logging level in the integration configuration if you need more troubleshooting information.
  4. On the Value Streams page, select the value stream that you created earlier in the tutorial.
  5. Click Configure value stream map > Download value stream map.
    The helloWorld-vsm.json file is downloaded to your computer.
    Note: After you modify the default value stream map file, the downloaded file name will reflect the name of the value stream.
  6. In your text editor, open the helloWorld-vsm.json file, and then add the Jira integration to the integrations array in the JSON file.
    Because you already defined the Jira integrations, you can add it to the value stream by referencing its name, as shown in the following example:
    "integrations": [
   {
    "name":"GitHub tutorial"
   }
  ],
    Of course, use the name you assigned to the integration in Step 3.
  7. In the helloWorld-vsm.json file.
  8. On the helloWorld value stream page, select Configure value stream map > Replace value stream map, and then select the JSON file that you modified.
    After the file uploads, refresh the helloWorld value stream page. A particle with the Jira status of Backlog appears in the Backlog stage, as shown in the following figure:
    Figure 1. Customized value stream

    If your Jira project has more than one issue with the status of Backlog, corresponding dots for all of them appear in the Backlog stage.

    Select the particle to display a card with information about the particle, including its history. Links to the associated Jira issue are provided.
    Figure 2. Particle information

Results

In this lesson, you integrated the external tool Jira into your value stream and used a DQL query to display data.

What to do next

In the next lesson, we add a DQL query that reflects changes to the integrated Jira issues.