Dispatch triggers

Mint can dispatch predefined runs via the CLI, an API call, or the UI. Dispatch triggers are useful for runs that need to be run on an ad-hoc basis, such as deploying an application.

Defining a dispatch trigger

Like event triggers, dispatch triggers are defined as an array in the on section of your run definition. Here's an example:

on:
  dispatch:
    - key: deploy-application
      init:
        commit-sha: ${{ event.git.sha }}
        deployment-target: ${{ event.dispatch.params.deployment-target }}
      params: [deployment-target]

Key

The key is required and must be unique within your entire organization. The key will be used to display the dispatch trigger in the Cloud UI, and it will also be used when dispatching the run via the API.

Params

The params array details the keys that will be available in the event.dispatch.params context when defining your init parameters. You can optionally specify for each param whether it is required, what its default value is, and how it should appear in the Cloud UI when dispatching the run:

on:
  dispatch:
    - key: deploy-application
      init:
        commit-sha: ${{ event.git.sha }}
        deployment-target: ${{ event.dispatch.params.deployment-target }}
      params:
        - key: deployment-target
          name: Deployment target
          description: The name of the environment to deploy to.
          default: staging
          required: true

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:
  dispatch:
    - key: deploy-application
      init:
        commit-sha: ${{ event.git.sha }}
        deployment-target: ${{ event.dispatch.params.deployment-target }}
      params: [deployment-target]
      title: Deploy application to ${{ init.deployment-target }}

Target

If you only want to run certain tasks when the run is dispatch, you can specify a target.

on:
  dispatch:
    - key: deploy-application
      init:
        commit-sha: ${{ event.git.sha }}
        deployment-target: ${{ event.dispatch.params.deployment-target }}
      params: [deployment-target]
      target: deploy

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

on:
  dispatch:
    - key: deploy-application
      init:
        commit-sha: ${{ event.git.sha }}
        deployment-target: ${{ event.dispatch.params.deployment-target }}
      params: [deployment-target]
      target: [prepare, deploy]

Dispatching a run

Once a dispatch trigger has been defined in a Mint workflow on a commit within your remote repository, you can dispatch a run using that dispatch trigger using the Mint CLI, the Mint API, or the Cloud UI.

Dispatching via the Mint CLI

Use the CLI's mint dispatch command. For example, to dispatch the deploy-application examples from above, you would run mint dispatch deploy-application --param deployment-target=staging

Dispatching via the API

Use the POST /mint/api/runs/dispatches endpoint to create a dispatch request and then poll GET /mint/api/runs/dispatches/:dispatch_id until the run ID for your dispatch is available. For example, the following curl:

curl -X POST https://cloud.rwx.com/mint/api/runs/dispatches \
  -H "Authorization: Bearer $RWX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"key": "deploy-application", "params": { "deployment-target": "staging" }, "ref": "main", "title": "Title for my run"}'

will result in a response status of 201 and a response body of {"dispatch_id": "1"}. You can then take that ID and curl:

curl -X GET https://cloud.rwx.com/mint/api/runs/dispatches/1 \
  -H "Authorization: Bearer $RWX_ACCESS_TOKEN" \
  -H "Accept: application/json"

which will result in a response status of 200 and one of the following response bodies:

Dispatching via the UI

To dispatch a run via the UI, navigate to the runs page and click "Dispatch a run." You'll see a list of your dispatch triggers; select the trigger to dispatch, and then

Dispatch refs

When dispatching a run, Mint will look up the dispatch trigger on the ref specified for the dispatch and use only that ref's dispatch trigger for determining which params are required. The specified ref will also be used to populate the event.git context and to unlock vaults. If a ref isn't specified, the default branch (such as main or master) on your repository will be used.

It's generally important to use event.git.sha, event.git.ref, event.git.branch, or event.git.tag instead of accepting a ref as a dispatch param. There are security implications to having a ref for a dispatch param. For example, if you were to do this:

on:
  dispatch:
    - key: my-dispatch
      init:
        # Don't do this! This is an example of what _not_ to do
        commit-sha: ${{ event.dispatch.params.commit-sha }}
      params: [commit-sha]

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

then any user in your organization could dispatch this run with --ref main --param commit-sha=not-main. If the run accesses locked vaults that are only unlocked by runs on main, then this run will be granted access to those vaults, but the cloned code will be the code from not-main. A compromised user in your organization could take advantage of this to exfiltrate secrets and OIDC tokens from your locked vault. For sensitive workflows, you should only trust the event.git context for your refs.