CI/CD has dramatically improved the software delivery experience over the last decade by introducing automatic quality checks, deployment pipelines, and a multitude of other services that help software developers be more productive. However, the proliferation of tooling has also contributed to growing complexity, and it’s becoming increasingly common for CI pipelines to stretch into dozens of specific actions that take as long as 20-30 minutes. These delays can be costly to software development teams that want to meet their productivity goals.

gitStream is a workflow automation tool for the code review process that enables you to use YAML to define code review policies and practices. We recently added functionality that lets you orchestrate CI Pipelines in GitHub to selectively trigger them based on the contents of a PR. With gitStream, you will no longer be required to run all CI services for every PR, reducing the amount of time your team spends waiting on things to finish so you can spend more time on productive work.

Let’s take a look at how to use gitStream to orchestrate your CI pipelines.

Install gitStream

gitStream is a GitHub app that you install to your repo or organization. Once installed, you can create Continuous Merge (CM) files that use YAML to define “if this, then that” rules for the code review process. To learn more about how to install gitStream and how it works, check out the documentation.

If you want to test out gitStream before diving into CI orchestration, we recommend trying out the automation that labels PRs with an estimated time to review. Dive into the rest of this article once you’re ready to move on with CI orchestration.

Configure Your GitHub Actions

Any GitHub Action you want to control with gitStream must be configured to support manual dispatch because this is the mechanism gitStream uses to trigger Actions. You will also want to make sure that there aren’t any automatic triggers in your workflow YAML file, otherwise those Actions will continue to run every time. For example, your workflow should use the on: workflow_dispatch component of this example:

name: My Workflow

on:
  workflow_dispatch:

jobs:
  say_hello:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Print Hello, World!
      run: echo "Hello, World!"

Create a Continuous Merge Configuration

Once gitStream is installed and you have an Action that is setup for manual dispatch, it’s time to create your first automation. Inside the repository’s .cm directory, create a new CM configuration file for your automation. One of the more common situations you might encounter that would benefit from CI orchestration is triggering specific pipelines based on the resources that are modified in a PR. 

For example, a PR might only modify code that affects your mobile app, an API, backend services, or other specific components of your software. You can configure gitStream to detect when resources are modified and automatically trigger the appropriate GitHub Actions for them. This example shows how to use gitStream to selectively trigger CI pipelines based on the modified resources.

dispatch_github_action.png
i# -*- mode: yaml -*-

manifest:
  version: 1.0
  
automations:
  {% for item in pipelines %}
  # Change pr.target to branch.name if you want to trigger on the source branch rather then the target branch.
  dispatch_github_action_{{ item.name }}:
    if:
      - {{ pr.target | includes(term=item.branch.prefix) }}
    run:
      - action: run-github-workflow@v1
        args:
          workflow: .github/workflows/{{ item.workflow }}
          check_name: {{ item.name }}
      - action: add-label@v1
        args:
          label: {{ item.label }}
  {% endfor %}


pipelines:
  - name: mobile-ci
    label: Mobile CI 
    branch-prefix: 'mobile-'
    workflow: mobile.yml
  - name: backend-ci
    label: Backend CI 
    branch-prefix: 'backend-'
    workflow: 'backend.yml'

Alternatively, you can also use gitStream to skip required status checks in situations where they aren't necessary. For example, you probably don't need all of your CI pipelines for PRs that only change docs.

# -*- mode: yaml -*-

manifest:
  version: 1.0

on:
  - pr_created
  - commit

automations:
  skip_github_action_resource:
    if:
      - {{ files | match(term='docs/') | every }}
    run:
      - action: add-github-check@v1
        args:
          check_name: release-ci
          conclusion: skipped
      - action: add-github-check@v1
        args:
          check_name: mobile-ci
          conclusion: skipped
      - action: add-comment@v1
        args:
          comment: |
          [gitStream](https://docs.gitstream.cm) automatically skipped production CI pipelines because this PR only contains docs changes.

Get these examples here.

Similarly, you can also do this based on the name of the branch or PR title, the labels that have been applied to the PR, or nearly any other aspect of the PR. Check out the docs for more information about what you can do with gitStream.

See gitStream in Action

Once you have a CM file committed to your repo’s primary branch, all you need to do is open or modify a PR that triggers the automation. Then, you can sit back and watch the workflow automation take action.

If you want to learn more about other ways to automate the code review process with gitStream check out the quickstart examples for common scenarios gitStream can help with or the integrations page to see a list of the third-party tools gitStream supports. If you want to get involved or give the project a star, check out the gitStream repo on GitHub.