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.github.push.head_commit.id }}

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

For all values available via the event.github.push context, 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 anytime 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.github.pull_request.pull_request.head.sha }}

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

Pull Request Closed

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

on:
  github:
    pull_request:
      actions: [closed]

When a pull request is closed, ${{ event.github.pull_request.pull_request.head.sha }} may point to a commit which no longer exists and cannot be cloned. This can happen based on your merge strategy, such as 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 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.2.2
    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: ${{ secrets.YOUR_ORG_CLONE_TOKEN }}

Actions

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

on:
  github:
    pull_request:
      actions: [opened]

Pull Request Context

For all values available via the event.github.pull_request context, 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 is 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, presently 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 conditionally trigger a new run in response to an event. For example, if you only want your definition to be triggered on pushes to main:

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