Workflows

Search…
Workflows
Workflows allow users to define simple, CI-like sequences of Garden commands and script steps, that can be run from a command line, in CI pipelines or directly triggered from PRs or branches using Garden Enterprise.
Custom shell scripts can be used for preparation ahead of running Garden commands, handling outputs from the commands, and more.
A sequence of commands executed in a workflow is also generally more efficent than scripting successive runs of Garden CLI commands, since state is cached between the commands, and there is no startup delay between the commands.
How it Works
Workflows are defined with a separate kind of configuration file, with a list of steps:
1
# workflows.garden.yml
2
kind: Workflow
3
name: my-workflow
4
steps:
5
  - ...
Copied!
We suggest making a workflows.garden.yml next to your project configuration in your project root. You can also place your workflow definitions in your project root project.garden.yml/garden.yml file (with a --- separator after the project configuration).
Each step in your workflow can either trigger Garden commands, or run custom scripts. The steps are executed in succession. If a step fails, the remainder of the workflow is aborted.
You can run a workflow by running garden run workflow <name>, or have it trigger automatically via Garden Enterprise.
Command steps
A simple command step looks like this:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - command: [deploy]  # runs garden deploy
Copied!
You can also provide arguments to commands, and even template them:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - command: [run, task, ${var.task-name}]  # runs a specific task, configured by the `task-name` variable
Copied!
Not all Garden commands can be run in workflows, and some option flags are not available. Please see the command reference to see which commands are supported in workflows.
The available keys for templating can be found in the template reference.
Script steps
A script step looks something like this:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - script: |
5
      echo "Hello there!"
Copied!
Scripts can also be templated:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - script: |
5
      echo "Hello ${project.name}!"
Copied!
Environment variables
To explicitly provide environment variables to the steps of a workflow, you can use the workflow.envVars field:
1
kind: Workflow
2
name: my-workflow
3
envVars:
4
  MY_ENV_VAR: some-value
5
  MY_PROJECT_VAR: ${var.my-var} # Use template strings
6
  SECRET_ACCESS_TOKEN: ${secrets.SECRET_ACCESS_TOKEN} # Use a Garden Enterprise secret
7
...
Copied!
Workflow-level environment variables like this can be useful e.g. for providing templated values (such as secrets or project variables) to several script steps, or to initialize providers in the context of a CI system.
Note that workflow-level environment variables apply to all steps of a workflow (both command and script steps).
The skip and when options
By default, a workflow step is run if all previous steps have been run without errors. Sometimes, it can be useful to override this default behavior with the skip and when fields on workflow steps.
The skip field is a boolean. If its value is true, the step will be skipped, and the next step will be run as if the skipped step succeeded.
Note that skipped steps don't produce any outputs (see the step outputs section below for more). However, skipped steps are shown in the command log.
The when field can be used with the following values:
onSuccess (default): This step will be run if all preceding steps succeeded or were skipped.
onError: This step will be run if a preceding step failed, or if its preceding step has when: onError. If the next step has when: onError, it will also be run. Otherwise, all subsequent steps are ignored. See below for more.
always: The step will always be run, regardless of whether any previous steps have failed.
never: The step will always be ignored, even if all previous steps succeeded. Note: Ignored steps don't show up in the command logs.
The simplest usage pattern for onError steps is to place them at the end of your workflow (which ensures that they're run if any step in your workflow fails):
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - command: [run, task, my-task]
5
  - command: [deploy]
6
  - command: [test]
7
  - script: |
8
      echo "Run if any of the previous steps failed"
9
    when: onError
10
  - script:
11
      echo "This task is always run, regardless of whether any previous steps failed."
12
    when: always
Copied!
A more advanced use case is to use onError steps to set up "error handling checkpoints" in your workflow.
For example, if the first step (run task my-task) fails in this workflow:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - command: [run, task, my-task]
5
  - script: |
6
      echo "Run if my-task step failed"
7
    when: onError
8
  - script: |
9
      echo "Also run if my-task step failed"
10
    when: onError
11
  - command: [deploy]
12
  - command: [test]
13
  - script: |
14
      echo "Run if the deploy or test steps failed"
15
    when: onError
16
  - script: | # Finally, an `always` step (for example, to clean up the staging environment)
17
      echo "This task is always run, regardless of whether any previous steps failed."
18
    when: always
Copied!
then the first two onError steps will be run, and all other steps will be skipped (except for the last one, since it has when: always). This can be useful for rollback operations that are relevant only at certain points in the workflow.
You can also template the values of skip and when for even more flexibility. For example:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - script: |
5
      echo "Fetching credentials for staging environment"
6
    skip: ${environment.name != "staging"} # This step is only run in the staging environment
7
  - command: [deploy]
8
  - script: |
9
      echo "Run if deploy step failed"
10
    when: onError
11
  - script: |
12
      echo "Also run if deploy step failed"
13
    when: onError
14
  - command: [build]
15
    when: never # This is never run
16
  - command: [test]
17
  - script: |
18
      echo "Run if test step failed, but not if the deploy step failed"
19
    when: onError
20
  - script: | # Finally, an `always` step (for example, to clean up the staging environment)
21
      echo "Clean up staging environment, regardless of whether the workflow succeeded or failed."
22
    when: "${environment.name == 'staging' ? 'always' : 'never'}"
Copied!
Step outputs
Workflow steps can reference outputs from previous steps, using template strings. This is particularly useful when feeding command outputs to custom scripts, e.g. for custom publishing flows, handling artifacts and whatever else you can think of.
For example, to retrieve a module version after a build:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - command: [build]
5
  - script: |
6
      echo "Built version ${steps.step-1.outputs.builds.my-module.version}"
Copied!
You can also set a name on a step, to make it easier to reference:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - name: build
5
    command: [build]
6
  - name: project-outputs
7
    command: [get, outputs]
8
  - script: |
9
      echo "Project output foo: ${steps.project-outputs.outputs.foo}"
Copied!
The schema of command outputs can be found in the command reference. Every step also exports a log key for the full command or script log.
Triggers
Garden Enterprise can monitor your project repository for updates, and trigger workflows automatically on e.g. PR and branch updates.
For example, here's how you'd trigger a workflow for PRs made from any feature/* branch:
1
kind: Workflow
2
name: my-workflow
3
steps:
4
  - ...
5
triggers:
6
  - environment: local
7
    events: [pull-request]
8
    branches: [feature/*]
Copied!
For a full description of how to configure triggers, check out the workflows reference.
Workflows and the Stack Graph
Unlike modules, workflows stand outside of the Stack Graph. They cannot currently depend on each other, and nothing in the Stack Graph can reference or otherwise depend on workflows.
Examples
Authenticate with Google Cloud before deploying a project
Here we use secrets (which are a Garden Enterprise feature) for the auth key, but you can replace those template keys with corresponding ${var.*} or ${local.env.*} keys as well.
1
kind: Workflow
2
name: deploy
3
steps:
4
  - name: gcloud-auth
5
    description: Authenticate with Google Cloud
6
    script: |
7
      export GOOGLE_APPLICATION_CREDENTIALS=$HOME/gcloud-key.json
8
      echo ${secrets.GCLOUD_SERVICE_KEY} > $GOOGLE_APPLICATION_CREDENTIALS
9
      gcloud auth activate-service-account --key-file=$GOOGLE_APPLICATION_CREDENTIALS
10
      gcloud --quiet config set project ${var.GOOGLE_PROJECT_ID}
11
      gcloud --quiet config set compute/zone ${var.GOOGLE_COMPUTE_ZONE}
12
      gcloud --quiet container clusters get-credentials ${var.GOOGLE_CLUSTER_ID} --zone ${var.GOOGLE_COMPUTE_ZONE}
13
      gcloud --quiet auth configure-docker
14
  - name: deploy
15
    command: [deploy]
Copied!
Next Steps
Take a look at our Variables and Templating section for details on how to use templating in your configuration files.
Also check out Using the CLI for CLI usage examples, and some common day-to-day usage tips.
Using Garden - Previous
Tasks
Next - Using Garden
Variables and templating
Last modified 2mo ago
Copy link
Contents
How it Works
Command steps
Script steps
Environment variables
The skip and when options
Step outputs
Triggers
Workflows and the Stack Graph
Examples
Authenticate with Google Cloud before deploying a project
Next Steps