As a Code Stream administrator or developer, you can integrate Code Stream cloud services with the Git lifecycle by using the Git trigger. When you make a code change in GitHub, GitLab, or Bitbucket Enterprise, the event communicates with Code Stream through a webhook and triggers a pipeline. The webhook works with GitLab, GitHub, and Bitbucket cloud and on-premises enterprise versions.

When you add the webhook for Git in Code Stream, it also creates a webhook in the GitHub, GitLab, or the Bitbucket repository. If you update or delete the webhook later, that action also updates or deletes the webhook in GitHub, GitLab, or Bitbucket.

Your webhook definition must include a Git endpoint on the branch of the repository that you will monitor. To create the webhook, Code Stream uses the Git endpoint. If the endpoint does not exist, you can create it when you add the webhook. This example assumes that you have a predefined Git endpoint in GitHub.

Note: Your Git endpoint must use a private token for authentication. If your Git endpoint uses a password for basic authentication, you will not be able to create a webhook.

You can create multiple webhooks for different branches by using the same Git endpoint and providing different values for the branch name in the webhook configuration page. To create another webhook for another branch in the same Git repository, instead of cloning the Git endpoint multiple times for multiple branches, you can provide the branch name in the webhook. This approach allows you to reuse the Git endpoint. If the branch in the Git webhook is the same as the branch in the endpoint, you don't need to provide branch name in the Git webhook page.

This example shows you how to use the Git trigger with a GitHub repository, but the prerequisites include preparations required if another Git server type is used.

Prerequisites

  • Verify that you are a member of a project in Code Stream. If you are not, ask a Code Stream administrator to add you as a member of a project. See How do I add a project in Code Stream.
  • Verify that you have a Git endpoint on the GitHub branch you want to monitor. See How do I integrate Code Stream with Git.
  • Verify that you have rights to create a webhook in the Git repository.
  • For the pipelines you want to trigger, verify that you have set the input properties to inject Git parameters when the pipeline runs.

    When you configure your pipeline to use the trigger for Git, you configure the input parameters on the Input tab.

Procedure

  1. In Code Stream, click Triggers > Git.
  2. Click the Webhooks for Git tab, then click New Webhook for Git.
    1. Select a project.
    2. Enter a meaningful name and description for the webhook.
    3. Select a Git endpoint configured for the branch you want to monitor.
      When you create your webhook, the webhook definition includes the current endpoint details.
      • If you later change the Git type, Git server type, or Git repository URL in the endpoint, the webhook will no longer be able to trigger a pipeline because it will try to access the Git repository using the original endpoint details. You must delete the webhook and create it again with the endpoint.
      • If you later change the authentication type, username, or private token in the endpoint, the webhook will continue to work.
      • If you are using a BitBucket repository, the URL for the repository must be in one of these formats: https://api.bitbucket.org/{user}/{repo name} or http(s)://{bitbucket-enterprise-server}/rest/api/1.0/users/{username}/repos/{repo name}.
      Note: If you previously created a webhook using a Git endpoint that uses a password for basic authentication, you must delete and redefine the webhook with a Git endpoint that uses a private token for authentication.
      See How do I integrate Code Stream with Git.
    4. (Optional) Enter the branch that you want the webhook to monitor.
      If you leave the branch unspecified, the webhook monitors the branch that you configured for the Git endpoint.
    5. (Optional) Generate a secret token for the webhook.
      If you use a secret token, Code Stream generates a random string token for the webhook. Then, when the webhook receives Git event data, it sends the data with the secret token. Code Stream uses the information to determine if the calls are coming from the expected source such as the configured GitHub instance, repository, and branch. The secret token provides an extra layer of security that is used to verify that the Git event data is coming from the correct source.
    6. (Optional) Provide file inclusions or exclusions as conditions for the trigger.
      • File inclusions. If any of the files in a commit match the files specified in the inclusion paths or regex, the pipelines will trigger. With a regex specified, Code Stream only triggers the pipelines when filenames in the changeset match the expression provided. The regex filter is useful when configuring a trigger for multiple pipelines on a single repository.
      • File exclusions. When all the files in a commit match the specified files in the exclusion paths or regex, the pipelines do not trigger.
      • Prioritize exclusions. When toggled on, Prioritize Exclusion ensures that pipelines do not trigger even if any of the files in a commit match the files specified in the exclusion paths or regex. The default setting is off.
      If conditions meet both the file inclusions and file exclusions, pipelines do not trigger.

      In the following example, both file inclusions and file exclusions are conditions for the trigger.

      File inclusions and file exclusions, and their values, appear on the Webhooks for Git tab in the trigger for Git, and can be plain or regex.

      • For file inclusions, a commit with any change to runtime/src/main/a.java or any Java file will trigger pipelines configured in the event configuration.
      • For file exclusions, a commit with changes only in both files will not trigger the pipelines configured in the event configurations.
    7. For the Git event, select a Push or Pull request.
    8. Enter the API Token.
      The CSP API token authenticates you for external API connections with Code Stream. To obtain the API token:
      1. Sign in to vRealize Automation Cloud.
      2. Click the drop-down arrow by your name.
      3. Click My Account.
      4. Click API Tokens.
      5. Click Generate Token.
        1. Enter a Token Name.
        2. Under Organization Roles, select Organization Owner.
        3. Under Service Roles, click to expand VMware Code Stream and select Code Stream Administrator.
        4. Click Generate.

          The Token Generated window displays a token with the name that you specified and the name of your organization.

      6. Click the COPY icon.

        Clicking COPY ensures that you capture the exact string and is more reliable than using your pointer to copy the string.

    9. Select the pipeline for the webhook to trigger.
      If the pipeline includes custom added input parameters, the Input Parameters list displays parameters and values. You can enter values for input parameters that pass to the pipeline with the trigger event. Or, you can leave the values blank, or use the default values if defined.

      For information about Auto inject input parameters for Git triggers, see the Prerequisites.

    10. Click Create.
      The webhook appears as a new card.
  3. Click the webhook card.
    When the webhook data form reappears, you see a webhook URL added to the top of the form. The Git webhook connects to the GitHub repository through the webhook URL.

    The Git webhook URL, which you copy and use in your Git repository, appears on the Webhooks for Git tab in the trigger for Git.

  4. In a new browser window, open the GitHub repository that connects through the webhook.
    1. To see the webhook that you added in Code Stream, click the Settings tab and select Webhooks.
      At the bottom of the webhooks list, you see the same webhook URL.

      In your GitHub repository, the list of webhooks displays the same Git webhook URL at the bottom of the list.

    2. To make a code change, click the Code tab and select a file on the branch. After you edit the file, commit the change.
    3. To verify that the webhook URL is working, click the Settings tab and select Webhooks again.
      At the bottom of the webhooks list, a green checkmark appears next to the webhook URL. When the Webhook in GitHub is valid, a green checkmark appears.
  5. Return to Code Stream to view the activity on the Git webhook. Click Triggers > Git > Activity.
    Under Execution Status, verify that the pipeline run has started.

    When a user commits a file, it activates the trigger for Git, and the Activity tab displays the status for the trigger as STARTED.

  6. Click Executions and track your pipeline as it runs.
    To observe the pipeline run, you can press the refresh button.

    After the pipeline triggers, the pipeline run displays the status as RUNNING.

Results

Congratulations! You successfully used the trigger for Git!