Call (Embedded Runs)

Embedded runs let you compose and coordinate multiple run definitions. Orchestrating your CI and CD workflows is one situation where this functionality shines.

Much like leaves, runs can be embedded using the call key. Before we dive into the details, let's consider the following example:

on:
  github:
    push:
      if: ${{ mint.run.git.branch == "main" }}
      init:
        git-ref: ${{ mint.run.git.sha }}
        only-at-the-top-level: some-value

tasks:
  - key: ci
    call: ${{ run.mint-dir }}/ci.yaml
    init:
      git-ref: ${{ mint.run.git.ref }}

  - key: cd
    call: ${{ run.mint-dir }}/cd.yaml
    after: ci
    init:
      git-ref: ${{ mint.run.git.ref }}
      image-id: ${{ tasks.ci.tasks.build-image.values.image-id }}

There's a lot to digest in this small example. Let's dive in.

call

Runs can be embedded via the call key. To do so, you must provide a value that starts with ${{ run.mint-dir }}. This expression represents the .mint directory that was present when your run was triggered. Following ${{ run.mint-dir }}, you provide the filename of the run definition you'd like to embed.

When your run is triggered, either via an event or with the CLI, Mint keeps track of the files in the .mint directory and exposes them to you for use in embedded runs.

Currently, only definitions that were present in the .mint directory when your run was triggered can be embedded. Future improvements to Mint will allow embedding runs from definitions produced during the triggered run.

init

Rather than providing parameters via with (like you would in leaves), you use init for embedded runs, just like you would if you were configuring a trigger for a run.

Embedded runs only have access to the init parameters which you explicitly provided. In the example above, init.only-at-the-top-level is not available to either embedded run and init.image-id is only available within the cd embedded run.

use

Embedded runs are isolated from one another. They do not share filesystems to ensure they behave the same way they would when run in isolation. Because of this, embedded run tasks cannot use another task and other tasks cannot use an embedded run task.

Instead, if you need to share information between embedded runs, you can access subtasks of embedded runs in expressions. In the example above, the ci embedded run has a subtask named build-image which produces an image-id value. The cd embedded run can access that value because it runs after ci. Leaves continue to be encapsulated and their subtasks are inaccessible (to provide better guarantees around breaking changes in leaves).

after

Even though use is not permitted with embedded runs, you can still configure order of execution and dependencies via after. In the example above, the cd embedded run will only run after the ci embedded run has successfully.

Tool Caches

When using tool caches, embedded runs will not share the same tool cache as the triggered run. Runs should declare their own tool caches to ensure they can run while embedded and in isolation. When a run is embedded, the subtasks of that run respect the tool cache declared in the embedded run's definition.

Concurrency Pools

When your embedded run definition uses a concurrency pool, Mint respects that definition and acquires a lease within that pool prior to starting any tasks within the embedded run.