As a Code Stream administrator or developer, you can integrate Code Stream with the Git life cycle 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 on-premises enterprise versions when both Cloud Assembly and the enterprise version are reachable on the same network.

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: To create a webhook your Git endpoint must use a private token for authentication, it cannot use a password.

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, you don't need to clone the Git endpoint multiple times for multiple branches. Instead, you provide the branch name in the webhook, which 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.
  • If configuring a webhook in GitLab, change the default network settings in GitLab enterprise to enable outbound requests and allow the creation of local webhooks.
    Note: This change is only required for GitLab enterprise. These settings do not apply to GitHub or Bitbucket.
    1. Log in to your GitLab enterprise instance as administrator.
    2. Go to network settings using a URL such as, http://{gitlab-server}/admin/application_settings/network.
    3. Expand Outbound requests and click:
      • Allow requests to the local network from web hooks and services.
      • Allow requests to the local network from system hook.
  • 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.

    For information about input parameters, see Planning a CICD native build in Code Stream before manually adding tasks.

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 commit triggers the pipelines. 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 VMware Cloud Services API token authenticates you for external API connections with Code Stream. To obtain the API token:
      1. Click Generate Token.
      2. Enter the email address associated with your user name and password and click Generate.
        The token that you generate is valid for six months. It is also known as a refresh token.
        • To keep the token as a variable for future use, click Create Variable, enter a name for the variable and click Save.
        • To keep the token as a text value for future use, click Copy and paste the token into a text file to save locally.
        You can choose to both create a variable and store the token in a text file for future use.
      3. Click Close.
    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 refresh.

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

Results

Congratulations! You successfully used the trigger for Git!