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.

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 integration.

    Integrations can be defined in several ways. You can define them directly in the JSON file's "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 tutorial.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 tutorial.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 linkRules section in the JSON file, define the rules that associate Git pull requests with Jira issues.

    DQL queries assigned to a stage filter the information that appears in the stage, as shown in the following example:

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

    Link rules define how integrated tools relate to one another. To define a link rule, specify a field in the linked-from tool that you want to associate with a field in the linked-to tool, and a regular expression that defines the matching pattern. In this case, you are linking Git pull requests to Jira issues.

  8. Add a query to the Merger stage, as shown in the following code example:

    { "name": "Development", "description": null, "stages": [ { "name": "In Progress", "query": "issue.status=\"In Progress\" AND deployment.env!=PROD ", "description": null, "wipLimit": null, "gates": null }, { "name": "Review", "query": "issue.status!=Done and pr.status=open", "description": null, "wipLimit": null, "gates": null }, { "name": "Merged", "query": "(pr.status=MERGED or pr.status=closed) AND build.status!=success AND deployment.env!=DEV and deployment.env!=PROD ", "description": null, "wipLimit": null, "gates": null },

  9. Save and then upload the modified JSON file.

Results

In this lesson, you integrated the external tool Git into the value stream and then linked it to Jira.

What to do next

In the next lesson, you learn how to create queries that produce data from the linked applications.

Parent topic: Linking value stream tools