Run Definitions Reference

on

The on key defines when runs will be kicked off. Mint will automatically kick off runs based on the triggers you specify inside of on.

For example, if you want to start a run whenever a push to main occurs, you could define a GitHub push trigger like this:

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

Triggers typically support if for defining conditions for the trigger, init for specifying init params for the triggered runs, target for specifying which tasks should run, and title for overriding the default title of triggered runs in the Mint UI.

on.github.[event]

Supported GitHub events are push and pull_request. When your run is triggered by an event, the JSON body of the event will be available under the event context. In this case, event.github.push or event.github.pull_request. Addition information about the event is available in event.git, such as the pushed branch name or the pushed commit.

All GitHub event triggers allow you to specify the init property which accepts an object of parameter name to expression. These init params are available within your run definition and are convenient when trying to separate what triggers your run from how your run executes. For example, parsing the commit message from a push event might look different than parsing it from a pull_request event.

The pull_request trigger additionally supports specification of the actions property which scopes that trigger to GitHub events with a matching action.

You can define multiple triggers of the same event by specifying the triggers as an array. The following run definition triggers a run of the test task whenever a push to any branch occurs, a run of the deploy task whenever a push to main occurs, and a run of the cleanup task whenever a pull request is closed:

on:
  github:
    push:
      - target: test
        init:
          commit-sha: ${{ event.git.sha }}
      - target: deploy
        if: ${{ event.git.branch == 'main' }}
        init:
          commit-sha: ${{ event.git.sha }}
        title: 'Deploy ${{ event.github.push.head_commit.message }}'
    pull_request:
      target: cleanup
      actions: [closed]
      init:
        gh-pull-request: ${{ event.github.pull_request.number }}
      title: 'Cleanup for PR #${{ init.gh-pull-request }}'

tasks: ...

concurrency-pools

Runs can be restricted to defined concurrency limits. Concurrency pools are the method to do so. You may specify multiple concurrency pools, each with different overflow behaviors, capacities, and conditions; however, only one concurrency pool can affect a given run at a time. In other words, concurrency pool conditions must be mutually exclusive.

A full example (in this case, to keep only the most recent run on a feature branch) looks like:

concurrency-pools:
  - id: my-org/my-repo:${{ init.branch }}
    if: ${{ init.branch != 'main' }}
    capacity: 1
    on-overflow: cancel-running

concurrency-pools[*].id

(supports expressions, contexts available X, Y, Z)

The id of a concurrency pool is the value which Mint restricts the capacity of. Runs evaluate the expression. If multiple are found to have the same value, the capacity and on-overflow behavior is applied to those runs.

This value is global across all of your organization’s runs. If you want to scope it to a particular repository or file, make sure to add additional detail to the id.

concurrency-pools[*].if

(supports expressions, contexts available X, Y, Z)

The if condition of a concurrency pool determines when Mint will consider the concurrency pool for a given run. The if condition must evaluate to true or false and defaults to true.

concurrency-pools[*].capacity

The capacity of a concurrency pool indicates how many runs may be running at once. Additionally, with an on-overflow strategy of cancel-waiting, there will be at most capacity additional runs waiting for the current runs to finish running.

concurrency-pools[*].on-overflow

The on-overflow behavior of a concurrency pool specifies what happens when runs under the same id continue to start. Possible values include cancel-running, cancel-waiting, and queue.

cancel-running: When a new run is started and its specified capacity is greater than the current number of running runs, it will start. Otherwise, the oldest run will be cancelled to make space for the new run.

cancel-waiting: When a new run is started and its specified capacity is greater than the current number of running runs, it will start. If there are already capacity runs running, and the capacity is greater than the number of queued runs, it will be queued and wait for a run to finish. Otherwise, the oldest queued run will be cancelled to make space for the new run to queue.

queue: When a new run is started and its specified capacity is greater than the current number of running runs, it will start. If there are already capacity runs running, it will be queued and wait for a run to finish.

tasks

The tasks of a run is a list of Task Definition. These tasks make up the behavior of the run when it is triggered. For more information on these, take a look at their reference.

A full example looks like:

tasks:
  - key: code
    call: mint/git-clone 1.4.0
    with:
      repository: [email protected]:your-org/your-repo.git
      ref: your-commit-sha
      ssh-key: ${{ secrets.YOUR_SSH_KEY_SECRET }}

  - key: run-tests
    use: code
    run: your-test-commmand-here