Git Trigger

GIT triggers are the most basic types of trigger for performing Continuous Integration with Codefresh.

At the trigger level you have the option of selecting

  • Which code repository will be used as a trigger
  • which branches will be affected by a pipeline
  • If a trigger will apply to a Pull Request or not

Note that you can select another repository other than the one the project itself belongs to. It is possible to trigger a build on project A even though a commit happened on project B.

You can also use Conditional expressions at the pipeline level to further fine-tune the way specific steps (or other transitive pipelines) are executed.

Manage GIT Triggers with Codefresh UI

To add a new GIT trigger, navigate to the Codefresh Pipeline Configuration view and expand the Triggers section. Press the Add Trigger button and select a GIT trigger type to add.

Adding new Trigger dialog

You can select the following information:

  • Git Provider - select that one that is linked with your account
  • Repository - You can select any repository even something different than the one that is used for the code checkout
  • Commit checkbox - If enabled will trigger this pipeline for any commit
  • PR checkboxes - Various checkboxes for filtering the Pull request event
  • Branch field - This is a regular expression and will only trigger for branches that match this naming pattern
  • Pull Request target branch - This is a regular expression and will trigger only when a Pull request is created against any branch that matches it
  • Modified files - This allows you to constrain the build and trigger it only if the modified files from the commit match this glob expression

Adding GIT Trigger

The commit checkbox (by default it is enabled) means that this pipeline will run for any commit as long as its source branch matches the naming scheme. This includes commits on pull requests.

The PR checkboxes mean that this pipeline will run only on the respective events that happen on a Pull Request. You can select multiple checkboxes to further fine-tune the exact event. If you are interested in all events select the checkbox Any Pull Request event.

The individual Pull request checkboxes are available only for Github repositories.

The Pull request target field allows you to trigger this pipeline only when the target of a Pull Request matches the branch name regular expression. Common examples here would be master or production.

The field Pull request target is available for all Git providers apart from Atlassian stash

The concept behind these checkboxes and branch name fields is to allow you to define which pipelines run for various workflows in your organization.

As a simple example you can have a production pipeline that runs only on master branch (and therefore the branch field says “master”) and a testing pipeline that runs user acceptance tests where only the Pull Request Open checkbox is active. This means that User Acceptance tests will run whenever a PR is created. Once it is merged the production pipeline will deploy the changes.

In a more advanced example you could add regular expressions in the branch field with names such as feature-, hotfix- etc and the PR checkbox active on different pipelines. This way you could trigger the pull requests only when they happen on specific branches. So a developer that creates a temporary feature with a name that doesn’t match these naming patterns will not trigger those pipelines.

The modified files field is a very powerful Codefresh feature that allows you to trigger a build only if the files affected by a commit are in a specific folder (or match a specific naming pattern). This means that you can have a big GIT repository with multiple projects and build only the parts that actually change.

Currently the field modified files is available only for Github and Gitlab repositories, since they are the only GIT providers that send this information in the webhook. We will support other GIT providers as soon as they add the respective feature.

Using the Modified files field to constrain triggers to specific folder/files

The modified field accepts glob expressions. The paths are relative to the root folder of the project (where the git repository was checked out). Some possible examples are:

**/package.json
**/Dockerfile*
my-subproject/**
my-subproject/sub-subproject/package.json
my-subproject/**/pom.xml

You can also use relative paths with dot-slash. Therefore ./package.json and package.json are exactly the same thing. They both refer to the file package.json found at the root of the git project that was checked out as part of the build.

Once a commit happens to a code repository, Codefresh will see which files are changed from the git provider and trigger the build only if the changed files match the glob expression. If there is no match no build will be triggered.

This is a very useful feature for organizations who have chosen to have multiple projects on the same GIT repository (monorepos). Let’s assume for example that a single system has a Java backend, a NestJS frontend and a Ruby-on-Rails internal dashboard.

GIT monorepo

Now we can define 3 different pipelines in Codefresh where each one builds the respective project

GIT monorepo pipelines

And then in the GIT trigger for each one we set the modified files field to the following values

  • For the build-nestjs-only pipeline MODIFIED FILES has my-nestjs-project/**
  • For the build-java-only pipeline MODIFIED FILES has my-java-project/**
  • For the build-rails-only pipeline MODIFIED FILES has my-rails-project/**

This way as multiple developers work on the git repository only the affected projects will actually build. A change to the NestJS project will not build the Rails project as well. Also if somebody changes only the README file and nothing else, no build will be triggered at all (which is a good thing as the source code is exactly the same).

You can also use Glob expressions for files. For example

  • an expression such my-subproject/sub-subproject/package.json will trigger a build only if the dependencies of this specific project are changed.
  • A pipeline with the expression my-subproject/**/pom.xml will trigger only if the Java dependencies for any project that belongs to my-subproject actually change.

Glob expressions have many more options not shown here. Visit the official documentation to learn more. You can also use the Glob Tester web application to test your glob expressions beforehand so that you are certain they match the files you expect them to match.

Using YAML and the Codefresh CLI to filter specific Webhook events

The default GUI options exposed by Codefresh are just a starting point for GIT triggers and pull requests. Using Codefresh YAML and the Codefresh CLI plugin you can further create two-phase pipelines where the first one decides which webwook events will be honored and the second one contains the actual build.

Two phase pipeline

The generic GIT trigger is placed on Pipeline A. This pipeline then filters the applicable webooks using conditional expressions. Then it uses the Codefresh CLI plugin (and specifically the run pipeline capability) to trigger pipeline B that performs build.

Some of the YAML variables that you might find useful (from the full list)

  • CF_PULL_REQUEST_ACTION - open, close, accept etc
  • CF_PULL_REQUEST_TARGET - target branch of the pull request
  • CF_BRANCH - the branch that contains the pull request

As an example, here is the codefresh.yml file of pipeline A where we want to run pipeline B only when a Pull Requested is opened against a branch named production.

codefresh.yml of pipeline A

version: '1.0'
steps:
  triggerstep:
    title: trigger
    image: codefresh/cli
    commands:
      - 'codefresh run <pipeline_B> -b=${{CF_BRANCH}}'
    when:
      condition:
        all:
          validateTargetBranch: '"${{CF_PULL_REQUEST_TARGET}}" == "production"'
          validatePRAction: '''${{CF_PULL_REQUEST_ACTION}}'' == ''opened'''

This is the build definition for the first pipeline that has a GIT trigger (with the Pull request checkbox enabled). It has only a single step which uses conditionals that check the name of the branch where the pull request is targeted to, as well as the pull request action. Only if both of these conditions are true then the build step is executed.

The build step calls the second pipeline. The end result is that pipeline B runs only when the Pull Request is opened the first time. Any further commits on the pull request branch will not trigger pipeline B (pipeline A will still run but the conditionals will fail).