Event Triggers

Mint can trigger runs based on certain events. Currently, GitHub push and pull_request events are supported.

Run on GitHub Push

Before configuring Mint to run on GitHub pushes, ensure you've followed the getting started with GitHub guide.

Placing the following snippet at the top of a Mint file will result in all tasks in the file running on every GitHub push.

on:
  github:
    push:

It's common to pass values from the event as init parameters into tasks.

on:
  github:
    push:
      init:
        commit-sha: ${{ event.git.sha }}

tasks:
  - key: code
    call: mint/git-clone 1.5.0
    with:
      repository: https://github.com/YOUR_ORG/PROJECT.git
      ref: ${{ init.commit-sha }}
      github-access-token: ${{ github.token }}

For all values available via the event context for GitHub push triggers, see the GitHub Push Trigger reference.

Run on GitHub Pull Request

Before configuring Mint to run on GitHub pull requests, ensure you've followed the getting started with GitHub guide.

Placing the following snippet at the top of a Mint file will result in all tasks in the file running any time a GitHub pull request is opened, reopened, or updated (synchronize).

on:
  github:
    pull_request:

It's common to pass values from the event as init parameters into tasks.

on:
  github:
    pull_request:
      init:
        commit-sha: ${{ event.git.sha }}

tasks:
  - key: code
    call: mint/git-clone 1.5.0
    with:
      repository: https://github.com/YOUR_ORG/PROJECT.git
      ref: ${{ init.commit-sha }}
      github-access-token: ${{ github.token }}

Pull Request Closed

You may also want to run tasks when pull requests are closed, which you can do by specifying actions: [closed].

on:
  github:
    pull_request:
      actions: [closed]

When a pull request is closed, ${{ event.git.sha }} may point to a commit that no longer exists and cannot be cloned. This can happen based on your merge strategy, like if you're using squash and merge. It can also happen if you close the PR without merging and have GitHub configured to delete the branch.

If you need to clone the repository to use a script within it, you should clone from a default branch. This is necessary to execute the logic that you want to run when pull requests are closed. It's common to clone from a default branch, such as main, instead of cloning the PR commit.

on:
  github:
    pull_request:
      actions: [closed]

tasks:
  - key: code
    call: mint/git-clone 1.5.0
    with:
      repository: https://github.com/your-org/your-repo.git
      ref: main # use scripts from from main since the PR commit gets deleted on close
      github-access-token: ${{ github.token }}

Actions

By default, Mint fires the pull request trigger on [opened, reopened, synchronze]. If you only want to handle certain actions, you can specify them:

on:
  github:
    pull_request:
      actions: [opened]

Pull Request Context

For all values available via the event context for GitHub pull request triggers, see the GitHub Pull Request Trigger reference.

Title

You can override the default title of your run by specifying the title. It accepts an expression and can use the mint, event, and init contexts. For example:

on:
  github:
    push:
      title: 'CI: ${{ event.github.push.head_commit.message}}'

Or:

on:
  github:
    pull_request:
      title: 'CI for PR #${{ event.github.pull_request.number }}'

Target

If you only want to run certain tasks on the event, you can specify a target under any trigger. Here's an example of specifying a target on a push event, but you can also specify targets for pull_request events.

on:
  github:
    push:
      target: task-key-to-run

If you want to target multiple tasks, pass them as an array.

on:
  github:
    push:
      target: [task-key1, task-key2]

Multiple Triggers

You can configure multiple triggers in a single file by passing them as an array. Mint will create one run per trigger.

on:
  github:
    push:
      - target: task-key-to-target
        init:
          param-to-set: value1
      - target: task-key-to-target
        init:
          param-to-set: value2

Because you can specify multiple tasks to target on a single trigger, the only reason to have multiple triggers is to have different init params. It's rare to need this, but it's supported.

Conditional Triggers

Triggers can specify if to trigger a new run conditionally in response to an event. For example, if you only want your definition to be triggered on pushes to main:

on:
  github:
    push:
      if: ${{ event.git.branch == 'main' }}
      init:
        commit-sha: ${{ event.git.sha }}

Paths

You may want to configure your CI workflow to only run when certain file paths change.

With Mint, this may not be necessary. If you have a filter on your task, it will be cached if the files listed in the filter do not change.

However, you may still have reasons for wanting to selectively run tasks. If so, you can use the github/compare leaf. The documentation for the leaf shows examples of checking the diff for both push and pull request triggers.