As a Code Stream administrator or developer, you can integrate Code Stream with the Gerrit code review life cycle by using the Gerrit trigger. The event triggers a pipeline to run when you create a patch set, publish drafts, merge code changes on the Gerrit project, or directly push changes on the Git branch.

When you add the Gerrit trigger, you select a Gerrit listener, a Gerrit project on the Gerrit server, and you configure Gerrit events. In the Gerrit listener definition, you select a Gerrit endpoint. If you need to update the Gerrit endpoint after connecting the listener, you must disconnect the listener first, then update the endpoint.

In this example, you first configure a Gerrit listener, then you use that listener in a Gerrit trigger with two events on three different pipelines.

Prerequisites

Procedure

  1. In Code Stream, click Triggers > Gerrit.
  2. (Optional) Click the Listeners tab, then click New Listener.
    Note: If the Gerrit listener that you plan to use for the Gerrit trigger is already defined, skip this step.
    1. Select a project.
    2. Enter a name for the Gerrit listener.
    3. Select a Gerrit endpoint.
    4. Enter the API Token.
      The CSP 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.
      If you created a variable, the API token displays the variable name that you entered by using dollar binding. If you copied the token, the API token displays the masked token.

      For on-premises instances, the Gerrit trigger listener uses a Gerrit endpoint, and an API token, which you can generate from the Listeners tab by clicking GENERATE TOKEN.

    5. To validate the token and endpoint details, click Validate.
      Your token expires after 90 days.
    6. Click Create.
    7. On the listener card, click Connect.
      The listener starts monitoring all activity on the Gerrit server and listens for any activated triggers on that server. To stop listening for a trigger on that server, you deactivate the trigger.
      Note: To update a Gerrit endpoint that is connected to a listener, you must disconnect the listener before updating the endpoint.
      • Click Configure > Triggers > Gerrit .
      • Click the Listeners tab.
      • Click Disconnect on the listener that is connected to the endpoint that you want to update.
  3. Click the Triggers tab, then click New Trigger.
  4. Select a project on the Gerrit server.
  5. Enter a name.
    The Gerrit trigger name must be unique.
  6. Select a configured Gerrit listener.
    By using the Gerrit listener, Code Stream provides a list of Gerrit projects that are available on the server.
  7. Select a project on the Gerrit server.
  8. Enter the branch in the repository that the Gerrit listener will monitor.
  9. (Optional) Provide file inclusions or exclusions as conditions for the trigger.
    • You provide file inclusions that trigger the pipelines. When any of the files in a commit match the files specified in the inclusion paths or regex, pipelines trigger. With a regex specified, Code Stream only triggers pipelines with filenames in the changeset that match the expression provided. The regex filter is useful when configuring a trigger for multiple pipelines on a single repository.
    • You provide file exclusions that keep pipelines from triggering. When all the files in a commit match the files specified in the exclusion paths or regex, the pipelines do not trigger.
    • Prioritize Exclusion, when toggled on, ensures that pipelines do not trigger. The pipelines won't trigger even if any of the files in a commit match the files specified in the exclusion paths or regex. The default setting for Prioritize Exclusion is turned off.
    If the conditions meet both the file inclusion and the file exclusion, pipelines do not trigger.

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

    The file inclusions and file exclusions appear as PLAIN pairs or REGEX pairs with values.

    • For file inclusions, a commit that has any change to runtime/src/main/a.java or any Java file will trigger the pipelines configured in the event configuration.
    • For file exclusions, a commit that has changes only in both files will not trigger the pipelines configured in the event configuration.
  10. Click New Configuration.
    1. For a Gerrit event, select Patchset Created, Draft Published, or Change Merged. Or, for a direct push to Git that bypasses Gerrit, select Direct Git push.
      Note: As of Gerrit release version 2.15, draft changes and draft change sets are no longer supported. So if you are running Gerrit release version 2.15 or later, Draft Published is not a supported event.
    2. Select the pipeline that will trigger.
      If the pipeline includes custom added input parameters, the Input Parameters list displays parameters and values. You can enter values for input parameters to be passed to the pipeline with the trigger event. Or, you can leave the values blank, or use the default values.
      Note: If default values are defined:
      • Any values you enter for the input parameters will override the default values defined in the pipeline model.
      • The default values in the trigger configuration will not change if the parameter values in the pipeline model change.

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

    3. For Patchset Created, Draft Published, and Change Merged, some actions appear with labels by default. You can change the label or add comments. Then, when the pipeline runs, the label or comment appears on the Activity tab as the Action taken for the pipeline.
      The Gerrit Event configuration allows you to enter comments by using a variable for the Success comment or Failure comment. For example: ${var.success} and ${var.failure}.
    4. Click Save.
    To add multiple trigger events on multiple pipelines, click New Configuration again.
    In the following example, you can see events for three pipelines:
    • If a Change Merged event occurs in the Gerrit project, the pipeline named Gerrit-Pipeline triggers.
    • If a Patchset Created event occurs in the Gerrit project, the pipelines named Gerrit-Trigger-Pipeline and Gerrit-Demo-Pipeline trigger.

    The configuration for the Gerrit listener and trigger includes the event types and the pipelines that can trigger.

  11. Click Create.
    The Gerrit trigger appears as a new card on the Triggers tab, and is set as Disabled by default.
  12. On the trigger card, click Enable.
    After you activate the trigger, it can use the Gerrit listener, which starts monitoring events that occur on the branch of the Gerrit project.
    To create a trigger that has the same file inclusion conditions or file exclusion conditions, but with a different repository than the one you included when you created the trigger, on the trigger card click Actions > Clone. Then, on the cloned trigger, click Open, and change the parameters.

Results

Congratulations! You successfully configured a Gerrit trigger with two events on three different pipelines.

What to do next

After you commit a code change in the Gerrit project, observe the Activity tab for the Gerrit event in Code Stream. Verify that the list of activities includes entries that correspond to every pipeline execution in the trigger configuration.

When an event occurs, only pipelines in the Gerrit trigger that relate to the particular type of event can run. In this example, if a patch set is created, only the Gerrit-Trigger-Pipeline and the Gerrit-Demo-Pipeline will run.

Information in the columns on the Activity tab describe each Gerrit trigger event. You can select the columns that appear by clicking the column icon that appears below the table.
  • The Change Subject and Execution columns are empty when the trigger was a direct Git push.
  • The Trigger for Gerrit column displays the trigger that created the event.
  • The Listener column is turned off by default. When you select it, the column displays the Gerrit listener that received the event. A single listener can appear as associated with multiple triggers.
  • The Trigger Type column is turned off by default. When you select it, the column displays the type of trigger as AUTOMATIC or MANUAL.
  • Other columns include Commit Time, Change#, Status, Message, Action taken, User, Gerrit project, Branch, and Event.

The Activity tab for the Gerrit trigger displays all the selected columns, and the relevant information in each column for all activity entries.

To control the activity for a completed or failed pipeline run, click the three dots at the left of any entry on the Activity screen.

  • If the pipeline fails to run because of a mistake in the pipeline model or another problem, correct the mistake and select Re-run, which runs the pipeline again.
  • If the pipeline fails to run because of a network connectivity issue or another problem, select Resume, which restarts the same pipeline execution, and saves run time.
  • Use View Execution, which opens the pipeline execution view. See How do I run a pipeline and see results.
  • Use Delete to delete the entry from the Activity screen.
If a Gerrit event fails to trigger a pipeline, you can click Trigger Manually, then select the trigger for Gerrit, enter the Change-Id, and click Run.
Note: Trigger Manually only works for valid Gerrit events such as Patchset created, Change Merged, and Draft-published.