Skip to main content

Your first actions in YAML

Learn how to define MintPress actions in a plain-text actions.yaml file, without writing any Ruby.

Feature preview

YAML actions are complete and supported for evaluation. The file format and its schema may still change before general availability, so keep actions.rb for production actions until then.

After following this guide you should know how to:

  • define an action that runs a command
  • break an action into child steps
  • pass a value from your properties into a command
  • pause a change for approval

Prerequisites​

This tutorial builds on the "Hello, world!" tutorial. Before you start, you must have:

  • a MintPress project with a Git remote connected to a Git repository you can write to
  • the ability to run changes in that project

Your first action​

In the root folder of your Git repository, create a file called actions.yaml containing:

actions:
  hello_world:
    description: Say hello
    run: echo "Hello world :-)"

Each entry under actions is an action, named by its key. run is the command the action executes, and description makes the action visible in the list of actions you can run.

Commit and push the file, then run a change as described in the "Hello, world!" tutorial, entering hello_world as the action and the new commit as the Git revision. The "Change logs" tab shows Loading actions.yaml before executing "hello_world" followed by the Hello world :-) message.

tip

You can keep an actions.rb in the same repository. MintPress loads both files when they are present.

tip

Your editor can complete and check actions.yaml as you type. See editor completion and validation.

Adding child steps​

An action can be made up of other actions, which MintPress runs as child steps. Replace the contents of actions.yaml with:

actions:
  prepare:
    run: echo "Getting ready"

  hello_world:
    run: echo "Hello world :-)"

  greet:
    description: Prepare, then say hello
    steps:
      - prepare
      - hello_world

Commit, push and run the greet action. The change now has two child steps, prepare and hello_world, which run one after the other. Each action runs only when you ask for it or when another action lists it as a step, so prepare and hello_world are not listed in the GUI because they have no description.

Using a value from your properties​

Commands often need a value that differs between environments, such as a name or a host. MintPress keeps these in properties. Add the following to the properties of your project (or one of its environments or assets):

{
  "greeting": {
    "name": "OpsChain"
  }
}

Then pass the value to the command with env. Update the hello_world action:

actions:
  prepare:
    run: echo "Getting ready"

  hello_world:
    env:
      NAME: '{{ properties.greeting.name }}'
    run: echo "Hello $NAME :-)"

  greet:
    description: Prepare, then say hello
    steps:
      - prepare
      - hello_world

{{ properties.greeting.name }} looks up the greeting.name property when the step runs, and the command reads it as the shell variable $NAME. Run greet again and the log now says Hello OpsChain :-). Change the property and run it again to see the new value used, without touching the Git repository.

caution

Always pass properties through env and refer to them as variables in the script. MintPress rejects a {{ }} expression written directly inside a run script. See passing values to a command for the reason.

Waiting for approval​

You can stop a change part-way through until someone approves it. Add an approval step between the two child steps:

actions:
  prepare:
    run: echo "Getting ready"

  hello_world:
    env:
      NAME: '{{ properties.greeting.name }}'
    run: echo "Hello $NAME :-)"

  greet:
    description: Prepare, then say hello once approved
    steps:
      - prepare
      - approval:
          step_name: Approve greeting
          requires_approval_from:
            - user_names: [your_username]
      - hello_world

Replace your_username with your MintPress username, then commit, push and run greet. The change runs prepare, then pauses at the Approve greeting step. Approve it from the change's page and the hello_world step runs. Use ldap_groups: [group-name] instead of user_names to allow everyone in an LDAP group to approve.

What to do next​