How gitStream Works
You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a
.cm extension, and they outline automations that will run whenever someone opens a new PR or makes changes to an existing PR.
CM files contain a combination of YAML and Jinja2 to build rules that follow an "if this, then that" approach to triggering and executing automations. This, combined with templating and gitStream-specific functions gives you a highly-flexible framework for building custom CM automations.
All CM files must have a section that starts with
automations: that contains one or more custom automations that will trigger for the repo. gitStream is triggered every time someone opens a new PR or changes an existing PR. Once activated, gitStream searches for applicable CM files and executes the automations that are listed inside them.
Here is an example of the basic components that are required in every CM file.
Required CM Components
Please note, this is not a valid CM automation, it is only for illustrative purposes.
When editing CM files, make sure you preserve the indentation in the examples because, like YAML, gitStream uses Python-style indentation to indicate nesting.
Automation actions specify the desired automations that should be triggered when all conditions are met. Each automation must include an
if condition and a
run section. The conditions are evaluated whenever someone creates a PR or makes changes to an existing PR; multiple conditions can be listed for a single automation, but they must all be true to invoke the actions. You can have any number of actions listed in one automation. Actions are invoked one-by-one in no particular order. PRs that are marked as Draft are ignored by default, but you can control that using explicit triggers.
Basic Automation Example
This example defines an automation named
welcome_newcomer that post a comment to welcome anyone who submits their first PR to the repo.
Context Variables and Filter Functions
Context variables are pre-defined objects that gitStream provides as the input data you will need to build your automations. These variables enable you to access information about things like the file names and paths, the person who submitted the PR, or what code was changed.
Filter functions are functions you can call and apply to variables. They are called with a pipe operator
| and can take arguments inside parentheses
( ). The logic expressions are based on Jinja2 syntax, supported by the Nunjucks library.
Context Variable and Filter Function Example
The following statement passes the context variable
files to the filter function
match which uses an optional list of sensitive filepaths that would need to be defined later in the CM file, and returns true if any of the files match the list as indicated by the
some filter function.
You can also apply Nunjucks logic operators to filters
Logic Operators Example
This example inverts the previous example using the keyword
Jinja templating makes it easy to write custom expressions that can be invoked elsewhere in your CM files. This makes it easy to reuse data, define custom criteria, and keep your configuration files cleaner so they're easier to manage.
Custom Expressions Example
This example contains two custom expressions;
is: contains a context variable and some filter functions that are invoked in the
sensitive_review automation via
sensitive directories contains a list of directory paths that will be matched in the filter function.
Ignore Files or Repos
You can provide gitStream with a list of specific files to ignore for all automations listed in the same CM file. To do so, add a
configuration: section to the CM file that you want to apply the exclusion list to. In the configuration section, add a list of files as an argument to the
How to Ignore Files
To ignore a list of files, add a
config.ignore_files to you CM file like this:
Similarly, if you are using gitStream for your entire git organization, you can specify repos to ignore in the
gitstream.cm file in the root directory of your cm repo.
Configuration Priority and Overrides
You can provide any number of CM files and automations for gitStream to process and you can freely combine organization-level automations with automations inside individual repos. There are two important things you need to keep in mind when doing this.
First, when a repository defines the same automation as an organization-level rule, the repository automation will take precedence and override the organization automation. The CM file name and the automation name must both match for this to take effect because gitStream identifies all automations based on a combination of both. For example, if you have a
gitstream.cm file that contains an automation named
my_automation, gitStream will identify that as
Second, no priority is given to individual automations. Instead, gitStream collects all applicable automations for a given PR and processes them all at once.
Write your first automation.
The best way to familiarize yourself with CM syntax is to build automations, and we've covered enough info for you to start!
If you're ready to start writing automations, check out our guide: Write Your First Automation.
Once you have gitStream installed and have run some automations, you can view details about them at app.gitstream.com. To view gitStream data, you will need to login with your GitHub account and have access to an organization that has run gitStream automations.
Once gitStream is installed and configured, there are several services that will interact with your repository whenever a PR is created or changed:
- The git service provider API (e.g. GitHub, Gitlab)
- The gitStream service that was installed from the git service provider marketplace.
- A gitStream CI/CD script that is configured for the git service provider (e.g. GitHub Actions, GitLab CI/CD).
- A gitStream agent the CI/CD script triggers to execute your automation.
Whenever a new PR is opened or an existing PR is changed, the following process occurs:
- The git service provider API notifies the gitStream service that an applicable change has occured to the PR which triggers a call to execute the gitStream CI/CD script.
- The gitStream CI/CD script executes the GitHub Action
linear-b/gitstream-github-action@v1on the repository, which looks for two things:
- Valid CM files that match the filepath
- Any CM files that are contained in the root directory of the organization's cm repo (if applicable).
- Valid CM files that match the filepath
- The gitStream CI/CD script passes all CM metadata to the gitStream agent which parses a list of all applicable CM rules.
- The GitStream agent provides the list of applicable automations to the gitStream service.
- The gitStream service iterates through the automations and updates the PR via the git service provider API.
Here is a diagram that illustrates how things work behind the scenes:
Upon completion, gitStream will show one of the following three statuses:
sequenceDiagram autonumber Git Provider API->>gitStream app: PR Notification activate gitStream app gitStream app->>gitStream CI/CD script: Execute CI/CD Action activate gitStream CI/CD script gitStream CI/CD script->>gitStream agent: CM Metadata activate gitStream agent gitStream agent->>gitStream app: Applicable Automations deactivate gitStream agent deactivate gitStream CI/CD script loop Automations loop Actions gitStream app->>Git Provider API: Update PR end end deactivate gitStream app
- Success - when the applicable automation finished and PR is good to go
- Neutral - when there aren't any applicable automations for the PR
- Failed - when the applicable automation finished without completion
gitStream checks have a 10-minute timeout for fail-safe reasons. If the check exceeds this time limit, the result will be displayed as Neutral - Skipped.
Avoid using these words when naming your automations, actions, or other components.
gitStream reserved words:
Nunjucks reserved words:
You can add support for
.cm in your code editor, see FAQ.
Is something missing?
If you find an issue with these docs or with gitStream itself, please search the gitStream issues page and create an issue if one doesn't already exist for your problem.