Git triggers

Learn how to run pipelines from Git events

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

At the trigger level, you can select:

• The code repository to be used as a trigger
• The branches affected by a pipeline
• If a trigger applies to a Pull Request (PR) or not

NOTE
You can select a 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.

Add Git triggers in Codefresh

Before you begin

Review:

• Git trigger settings
• Working with Git triggers

How to

1. In the Codefresh UI, from the sidebar, select Pipelines.
2. Select the pipeline to which to add the trigger, and then click the Workflow tab.
3. On the right, click Triggers, and then click Add Trigger.
4. Click Git, click Next and then configure the trigger settings.

Git trigger settings

Trigger settings can be grouped into:

• General settings
• Filter settings
• Advanced settings

General settings for Git triggers

GitHub trigger events

For a description of the events, see GitHub documentation.

• Push commits
• Push tags
• Any pull request event
• Pull request opened
• Pull request closed
• Pull request merged
• Pull request closed (not merged)
• Pull request reopened
• Pull request edited
• Pull request assigned
• Pull request unassigned
• Pull request review requested
• Pull request review request removed
• Pull request labeled
• Pull request unlabeled
• Pull request synchronized
• Pull request comment added (restricted)
• Pull request comment added
• Pull request review approved
• Pull request review commented
• Pull request review changes requested
• Release published
• Release unpublished
• Release created
• Release edited
• Release deleted
• Release prereleased
• Release released

Azure DevOps trigger events

For a description of the events, see Azure DevOps documentation.

• Push commits
• Any pull request event
• Pull request created
• Pull request merged
• Pull request updated

Bitbucket Cloud trigger events

For a description of the events and their payload, see Bitbucket Cloud documentation.

• Commit
• Push tags
• Push new branch
• Any pull request event
• Pull request created
• Pull request updated
• Pull request approved
• Pull request approval
• Pull request merged
• Pull request declined
• Pull request comment created
• Pull request comment updated
• Pull request comment deleted

Bitbucket Data Center trigger events

For a description of the events and their payload, see Bitbucket Data Center documentation.

• Commit
• Push commits
• Push new branch
• Delete branch
• Any pull request event
• Pull request created
• Pull request updated
• Pull request merged
• Pull request deleted
• Pull request declined
• Pull request approved
• Pull request approval
• Pull request push commit
• Pull request needs work
• Pull request comment deleted
• Pull request comment created
• Pull request comment updated
• Pull request push commit

GitLab trigger events

For a description of the events, see GitLab documentation.

• Commit
• Any Pull request event
• Pull request opened
• Pull request edited
• Pull request closed
• Pull request merged
• Pull request push commit

Gerrit trigger events

For a description of the events, see Gerrit documentation.

A Ref updated trigger event in Gerrit is mapped in Codefresh to Push commits or Push tags trigger events.

• Push commits (Ref updated in Gerrit)
• Push tags (Ref updated in Gerrit)
• Change abandoned
• Change deleted
• Change merged
• Change restored
• Comment added
• Hashtags changed
• Patchset created
• Reviewer added
• Reviewer deleted
• Topic changed
• WIP state changed
• Vote deleted

Filter settings for Git triggers

Advanced settings for Git triggers

Working with Git triggers

Skip triggering pipeline on commit

The default behavior triggers the pipeline on a commit action.
Override the default behavior by adding any one of the predefined strings anywhere in the commit message.

NOTE
Remember to include the opening and closing square brackets when adding the strings.

• [skip ci]
• [ci skip]
• [no ci]
• [skip codefresh]
• [codefresh skip]

Pull requests from comments

Pull requests from comments are supported for all Git providers, for both private and public repositories.
There are two options:

• Pull request comment added (restricted) This option triggers an event only when the PR comments are made by repository owners or collaborators.

• Pull request comment added
  This option triggers an event when PR comments are made by any user, regardless of their permissions.
  Because it is not restricted to owners and collaborators, this option is useful in GitHub, to enable triggers for PR comments made by users in GitHub teams.

  NOTE
  We strongly recommend selecting this option only for private repositories.

Pull Request Target Branch and Branch

The Pull Request Target Branch option allows you to trigger the pipeline only when the target of a Pull Request (PR), that is, where the PR will be merged to, matches the branch name in the regular expression. Common examples for branch names would be master or production.

NOTE
The Pull Request Target Branch option is available for all Git providers, except Atlassian Stash.

When using Terraform, please use the Go regex syntax as some Perl regex syntax is not compatible.

This option has meaning when a commit happens in the context of a PR, and in that case:

1. The Branch field looks at the branch that the commit is happening on
2. The PR Target Branch field will look at the branch the PR is happening against

For example, if you create a commit on a branch named my-feature, which is currently part of PR against branch staging (i.e. somebody wants to merge my-feature TO staging) then:

1. The BRANCH field value will try to match against my-feature
2. the PULL REQUEST TARGET BRANCH will try to match against staging

Here are some more syntax examples:

• /^((qa-release)$).*/g: Only run if branch is named qa-release.
• /^((production)$).*/g: Only run if branch is named production.
• /release/g: Only run if branch name contains release as substring.
• /feature-/gi; Only run if branch is feature-foo, feature-bar, my-feature-123 etc.
• /^((?!^feature).)*$/gi: Only run if branch name does not start with feature.

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.

Notice also that you can use Negative Lookahead in your Branch (Regex Expression) filter. An example to exclude tag events: /^((?!tag)).*/gi (the pattern here for tags to exclude is that they begin with tag…).

This will make all push-events (including tags) that do follow the tag... pattern to be excluded. Therefore, all tags like tag1, tag-X won’t trigger the pipeline.

Build pull requests from forks

By default, the Git trigger works for events coming from your personal repository. You can also use triggers from events that are coming from forks. This is a very useful feature for open source projects, as it allows you to run your own unit tests and other checks against a new feature before actually merging it in your repo.

To enable this behavior:

• Toggle the support pull request events from forks switch
• Select Pull request comment added (restricted)
• In the pr comment field enter a custom string (accepts regex)

Then once a contributor creates a fork of your repository and submits a pull request, you can review the code and then add a comment on your own that matches the PR comment expression.

Once that is done, Codefresh will launch your pipeline against the pull request. If you manage an open source project with Codefresh, remember to enable public builds as well.

When supporting building of pull requests from forks there are a few “gotchas” to look out for:

• Only comments made by repository owners and collaborators will result in the pipeline being triggered.
• Only Git pushes by collaborators within the GitHub organization will result in the pipeline being triggered
• If the repository is in a GitHub organization, comments made by private members of the organization will not activate the trigger, even if they are set as an owner or collaborator. Private members means that they need to be explicitly added to the repository. Access cannot be “inherited” by the GitHub team. Currently, only comments from Admins, or Collaborators (directly added, not via teams) are allowed, in order to be caught by this filter.
• The Pull request comment added checkbox should likely be the only one checked, or your pipeline may trigger on other events that you don’t anticipate.

Monorepo support (Modified files)

The Modified files option is a very powerful Codefresh option 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.

NOTE
Currently, the option is supported only for GitHub, GitLab, Azure DevOps, Bitbucket Data Center, Bitbucket (Cloud), and Gerrit. We will support other Git providers as soon as they add the respective feature.

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

The Modified files option 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/**
my-subproject/sub-subproject/package.json
my-subproject//pom.xml
!config/**

You can also define multiple expressions like this, with a maximum of 65k characters for the field:

{app/*,test/**}
{/package.json,my-subproject/**}
!{deployment/*,/version.cfg}

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.

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

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 as 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
• An expression such as !config/manifest.yaml will trigger a build if any file was changed apart from config/manifest.yaml

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.

Set minimum disk space for build volume by trigger

Set the disk space you need for the build volume in the context of the selected trigger. Setting the disk space for the trigger overrides that set for the pipeline.

1. In Workflow > Triggers, expand Advanced Options.
2. From the Runtime Environment list, select Override pipeline settings, and then select the runtime for which to override the pipeline setting.
3. If required, change the resource size.
4. Enable Set minimum disk space, and then change as required.

Manually adding trigger information

When creating a Git trigger in codefresh, sometimes the Git Integration does not have the permissions to create a webhook on the designated repository. When this happens, you get the following error: Failed to add Trigger.

This error means that Codefresh could not create the webhook and verify that it works. With that, Codefresh will mark the Trigger as Unverified. Two additional fields (Endpoint and Secret) will appear under the “Verify Trigger” button when you get this error.

• Endpoint: This will be the Webhook URL for the created Trigger
• Secret: Token to add to Github for verification.

Once you close the dialog box for adding a git trigger, the only way to get the Endpoint and Secret is via the API or CLI.

CLI

codefresh get pipeline Project/Pipeline -o yaml

API

# Project/Pipeline needs to be URL encode to be Project%2FPipeline
# / is URL encode to %2F

curl \
-X GET \
-H "Authorization: ${CF_API_KEY}" \
"https://g.codefresh.io/api/pipelines/Project%2FPipeline"

The spec.triggers displays information about each Git trigger. Look at the endpoint and secret fields for each Git trigger.

Adding a webhook to GitHub

1. When you receive the Failed to add Trigger, log into GitHub.
   • Make sure this user can access the repository settings and create Webhooks
2. Go to the repository mentioned in the “REPOSITORY” section from Unverified Trigger.
3. Go to Settings > Webhooks and click the “Add webhook” button.
4. Fill in the form
   • Payload URL: The URL from the Endpoint field from the Trigger
   • Content type: application/json
   • Secret: The token in the Secret field from the Trigger
   • SSL verification: Enable SSL verification
   • Events:
     1. Select let me select individual events
     2. Match the items selected in the Trigger By field from the Trigger
   • Active: Make sure this is selected
5. Click “Add webhook” when done.
6. Click “Done” in the Add Trigger form.
7. Test your webhook by making an event in the repository that will cause the Trigger to start the build.

NOTES

• You are responsible for syncing the Trigger By to the Events sent to us for the webhook. You can select “Send me everything” if you do not want to manually match the Trigger By in the Trigger with the Webhook Events in GitHub.
• The Trigger will remain “Unverified” until the integration has the correct permissions to the repository.

Accessing webhook content of the trigger directly

If your Git trigger is coming from GitHub, you can also access the whole payload of the webhook that was responsible for the trigger. The webhook content is available at /codefresh/volume/event.json. You can read this file in any pipeline step and process it like any other json file (e.g. with the jq utility).

codefresh.yml

version: '1.0'
steps:
  read_trigger_webook:
    title: "Reading Github webhook content"
    type: "freestyle"
    image: "alpine:3.9"
    commands:
      - 'cat /codefresh/volume/event.json'

Notice however that this file is only available when the pipeline is triggered from a GitHub event. If you manually run the pipeline, the file is not present.

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 webhook events will be honored and the second one contains the actual build.

The generic Git trigger is placed on Pipeline A. This pipeline then filters the applicable webhooks 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, synchronize, assign 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}}' -t <pipeline-b-trigger-name>
    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).

Related articles

Triggers in pipelines
Cron triggers
Creating pipelines
Using multi-git triggers