LogoLogo
Bonsai (0.13) DocsGitHubDiscord CommunityGarden Enterprise
Docs Edge
Docs Edge
  • Welcome to Garden!
  • Overview
    • What is Garden
    • Use Cases
      • Isolated On-Demand Preview Environments
      • Fast, Portable CI Pipelines that Run Anywhere
      • Shift Testing Left
      • Local Development With Remote Clusters
      • Jumpstart your Internal Developer Platform
    • Garden vs Other Tools
  • Getting Started
    • Quickstart
    • Garden Basics
    • Next Steps
  • Tutorials
    • Your First Project
      • 1. Create a Garden Project
      • 2. Pick a Kubernetes Plugin
      • 3. Add Actions
      • 4. Add Tests
      • 5. Code Syncing (Hot Reload)
      • 6. Next Steps
    • Setting up a Kubernetes cluster
      • 1. Create a Cluster
        • AWS
        • GCP
        • Azure
      • 2. Configure Container Registry
        • AWS
        • GCP
        • Azure
        • Docker Hub
      • 3. Set Up Ingress, TLS and DNS
      • 4. Configure the Provider
  • Using Garden With
    • Containers
      • Using Remote Container Builder
      • Building Containers
    • Kubernetes
      • Using Remote Kubernetes
      • Using Local Kubernetes
      • Deploying K8s Resources
      • Installing Helm charts
      • Running Tests and Tasks
    • Terraform
      • Using Terraform
      • Applying Terrform Stacks
    • Pulumi
      • Using Pulumi
      • Applying Pulumi Stacks
    • Local Scripts
  • Features
    • Remote Container Builder
    • Team Caching
    • Variables and Templating
    • Config Templates
    • Workflows
    • Code Synchronization
    • Custom Commands
    • Remote Sources
  • Guides
    • Connecting a Project
    • Environments and Namespaces
    • Installing Garden
    • Including/Excluding files
    • Installing Local Kubernetes
    • Migrating from Docker Compose to Garden
    • Using the CLI
    • Using Garden in CircleCI
    • Minimal RBAC Configuration for Development Clusters
    • Deploying to Production
    • Using a Registry Mirror
    • Local mode
  • Reference
    • Providers
      • container
      • ephemeral-kubernetes
      • exec
      • jib
      • kubernetes
      • local-kubernetes
      • otel-collector
      • pulumi
      • terraform
    • Action Types
      • Build
        • container Build
        • exec Build
        • jib-container Build
      • Deploy
        • configmap Deploy
        • container Deploy
        • exec Deploy
        • helm Deploy
        • kubernetes Deploy
        • persistentvolumeclaim Deploy
        • pulumi Deploy
        • terraform Deploy
      • Run
        • container Run
        • exec Run
        • helm-pod Run
        • kubernetes-exec Run
        • kubernetes-pod Run
      • Test
        • container Test
        • exec Test
        • helm-pod Test
        • kubernetes-exec Test
        • kubernetes-pod Test
    • Template Strings
      • Project template context
      • Environment template context
      • Provider template context
      • Action (all fields) template context
      • Action spec template context
      • Module template context
      • Remote Source template context
      • Project Output template context
      • Custom Command template context
      • Workflow template context
      • Template Helper Functions
    • Commands
    • Project Configuration
    • ConfigTemplate Reference
    • RenderTemplate Reference
    • Workflow Configuration
    • Garden Containers on Docker Hub
    • Glossary
    • Module Template Configuration
    • Module Types
      • configmap
      • container
      • exec
      • helm
      • jib-container
      • kubernetes
      • persistentvolumeclaim
      • pulumi
      • templated
      • terraform
  • Misc
    • FAQ
    • Troubleshooting
    • Telemetry
    • How Organizations Adopt Garden
    • New Garden Cloud Version
    • Migrating to Bonsai
  • Contributing to Garden
    • Contributor Covenant Code of Conduct
    • Contributing to the Docs
    • Setting up Your Developer Environment
    • Developing Garden
    • Config Resolution
    • Graph Execution
Powered by GitBook
On this page
  • YAML Schema
  • Configuration Keys
  • kind
  • name
  • description
  • envVars
  • files[]
  • files[].path
  • files[].data
  • files[].secretName
  • keepAliveHours
  • resources
  • resources.requests
  • resources.requests.cpu
  • resources.requests.memory
  • resources.limits
  • resources.limits.cpu
  • resources.limits.memory
  • limits
  • limits.cpu
  • limits.memory
  • steps[]
  • steps[].name
  • steps[].command[]
  • steps[].description
  • steps[].envVars
  • steps[].script
  • steps[].skip
  • steps[].when
  • steps[].continueOnError
  • triggers[]
  • triggers[].environment
  • triggers[].namespace
  • triggers[].events[]
  • triggers[].branches[]
  • triggers[].baseBranches[]
  • triggers[].ignoreBranches[]
  • triggers[].ignoreBaseBranches[]

Was this helpful?

  1. Reference

Workflow Configuration

PreviousRenderTemplate ReferenceNextGarden Containers on Docker Hub

Last updated 1 month ago

Was this helpful?

Below is the schema reference for configuration files.

The reference is divided into two sections:

  • contains the config YAML schema

  • describes each individual schema key for the configuration files.

YAML Schema

The values in the schema below are the default values.

kind: Workflow

# The name of this workflow.
name:

# A description of the workflow.
description:

# A map of environment variables to use for the workflow. These will be available to all steps in the workflow.
envVars: {}

# A list of files to write before starting the workflow.
#
# This is useful to e.g. create files required for provider authentication, and can be created from data stored in
# secrets or templated strings.
#
# Note that you cannot reference provider configuration in template strings within this field, since they are resolved
# after these files are generated. This means you can reference the files specified here in your provider
# configurations.
files:
  - # POSIX-style path to write the file to, relative to the project root (or absolute). If the path contains one
    # or more directories, they are created automatically if necessary.
    # If any of those directories conflict with existing file paths, or if the file path conflicts with an existing
    # directory path, an error will be thrown.
    # **Any existing file with the same path will be overwritten, so be careful not to accidentally overwrite files
    # unrelated to your workflow.**
    path:

    # The file data as a string.
    data:

    # The name of a Garden secret to copy the file data from (Garden Cloud only).
    secretName:

# The number of hours to keep the workflow pod running after completion.
keepAliveHours: 48

resources:
  requests:
    # The minimum amount of CPU the workflow needs in order to be scheduled, in millicpus (i.e. 1000 = 1 CPU).
    cpu:

    # The minimum amount of RAM the workflow needs in order to be scheduled, in megabytes (i.e. 1024 = 1 GB).
    memory:

  limits:
    # The maximum amount of CPU the workflow pod can use, in millicpus (i.e. 1000 = 1 CPU).
    cpu:

    # The maximum amount of RAM the workflow pod can use, in megabytes (i.e. 1024 = 1 GB).
    memory:

limits:
  # The maximum amount of CPU the workflow pod can use, in millicpus (i.e. 1000 = 1 CPU).
  cpu:

  # The maximum amount of RAM the workflow pod can use, in megabytes (i.e. 1024 = 1 GB).
  memory:

# The steps the workflow should run. At least one step is required. Steps are run sequentially. If a step fails,
# subsequent steps are skipped.
steps:
  - # An identifier to assign to this step. If none is specified, this defaults to "step-<number of step>", where
    # <number of step> is the sequential number of the step (first step being number 1).
    #
    # This identifier is useful when referencing command outputs in following steps. For example, if you set this
    # to "my-step", following steps can reference the ${steps.my-step.outputs.*} key in the `script` or `command`
    # fields.
    name:

    # A Garden command this step should run, followed by any required or optional arguments and flags.
    #
    # Note that commands that are _persistent_—e.g. the dev command, commands with a watch flag set, the logs command
    # with following enabled etc.—are not supported. In general, workflow steps should run to completion.
    #
    # Global options like --env, --log-level etc. are currently not supported for built-in commands, since they are
    # handled before the individual steps are run.
    command:

    # A description of the workflow step.
    description:

    # A map of environment variables to use when running script steps. Ignored for `command` steps.
    #
    # Note: Environment variables provided here take precedence over any environment variables configured at the
    # workflow level.
    envVars: {}

    # A bash script to run. Note that the host running the workflow must have bash installed and on path.
    # It is considered to have run successfully if it returns an exit code of 0. Any other exit code signals an error,
    # and the remainder of the workflow is aborted.
    #
    # The script may include template strings, including references to previous steps.
    script:

    # Set to true to skip this step. Use this with template conditionals to skip steps for certain environments or
    # scenarios.
    skip: false

    # If used, this step will be run under the following conditions (may use template strings):
    #
    # `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.
    #
    # `always`: This step will always be run, regardless of whether any preceding steps have failed.
    #
    # `never`: This step will always be ignored.
    #
    # See the [workflows guide](https://docs.garden.io/cedar-0.14/features/workflows#the-skip-and-when-options) for
    # details
    # and examples.
    when: onSuccess

    # Set to true to continue if the step errors.
    continueOnError: false

# A list of triggers that determine when the workflow should be run, and which environment should be used (Garden
# Cloud only).
triggers:
  - # The environment name (from your project configuration) to use for the workflow when matched by this trigger.
    environment:

    # The namespace to use for the workflow when matched by this trigger. Follows the namespacing setting used for
    # this trigger's environment, as defined in your project's environment configs.
    namespace:

    # A list of [GitHub
    # events](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads) that
    # should trigger this workflow.
    #
    # See the Garden Cloud documentation on [configuring
    # workflows](https://cloud.docs.garden.io/getting-started/workflows) for more details.
    #
    # Supported events:
    #
    # `pull-request`, `pull-request-closed`, `pull-request-merged`, `pull-request-opened`, `pull-request-reopened`,
    # `pull-request-updated`, `push`
    #
    #
    events:

    # If specified, only run the workflow for branches matching one of these filters. These filters refer to the
    # pull/merge request's head branch (e.g. `my-feature-branch`), not the base branch that the pull/merge request
    # would be merged into if approved (e.g. `main`).
    branches:

    # If specified, only run the workflow for pull/merge requests whose base branch matches one of these filters.
    baseBranches:

    # If specified, do not run the workflow for branches matching one of these filters. These filters refer to the
    # pull/merge request's head branch (e.g. `my-feature-branch`), not the base branch that the pull/merge request
    # would be merged into if approved (e.g. `main`).
    ignoreBranches:

    # If specified, do not run the workflow for pull/merge requests whose base branch matches one of these filters.
    ignoreBaseBranches:

Configuration Keys

kind

Type
Allowed Values
Default
Required

string

"Workflow"

"Workflow"

Yes

name

The name of this workflow.

Type
Required

string

Yes

Example:

name: "my-workflow"

description

A description of the workflow.

Type
Required

string

No

envVars

A map of environment variables to use for the workflow. These will be available to all steps in the workflow.

Type
Default
Required

object

{}

No

files[]

A list of files to write before starting the workflow.

This is useful to e.g. create files required for provider authentication, and can be created from data stored in secrets or templated strings.

Note that you cannot reference provider configuration in template strings within this field, since they are resolved after these files are generated. This means you can reference the files specified here in your provider configurations.

Type
Default
Required

array[object]

[]

No

files[].path

POSIX-style path to write the file to, relative to the project root (or absolute). If the path contains one or more directories, they are created automatically if necessary. If any of those directories conflict with existing file paths, or if the file path conflicts with an existing directory path, an error will be thrown.Any existing file with the same path will be overwritten, so be careful not to accidentally overwrite files unrelated to your workflow.

Type
Required

posixPath

No

Example:

files:
  - path: ".auth/kubeconfig.yaml"

files[].data

The file data as a string.

Type
Required

string

No

files[].secretName

The name of a Garden secret to copy the file data from (Garden Cloud only).

Type
Required

string

No

keepAliveHours

The number of hours to keep the workflow pod running after completion.

Type
Default
Required

number

48

No

resources

Type
Required

object

No

resources.requests

Type
Default
Required

object

{"cpu":50,"memory":64}

No

resources.requests.cpu

The minimum amount of CPU the workflow needs in order to be scheduled, in millicpus (i.e. 1000 = 1 CPU).

Type
Required

number

No

resources.requests.memory

The minimum amount of RAM the workflow needs in order to be scheduled, in megabytes (i.e. 1024 = 1 GB).

Type
Required

number

No

resources.limits

Type
Default
Required

object

{"cpu":1000,"memory":1024}

No

resources.limits.cpu

The maximum amount of CPU the workflow pod can use, in millicpus (i.e. 1000 = 1 CPU).

Type
Required

number

No

resources.limits.memory

The maximum amount of RAM the workflow pod can use, in megabytes (i.e. 1024 = 1 GB).

Type
Required

number

No

limits

Deprecated: Please use the resources.limits field instead.

Type
Required

object

No

limits.cpu

The maximum amount of CPU the workflow pod can use, in millicpus (i.e. 1000 = 1 CPU).

Type
Required

number

No

limits.memory

The maximum amount of RAM the workflow pod can use, in megabytes (i.e. 1024 = 1 GB).

Type
Required

number

No

steps[]

The steps the workflow should run. At least one step is required. Steps are run sequentially. If a step fails, subsequent steps are skipped.

Type
Default
Required

array[object]

[]

Yes

steps[].name

An identifier to assign to this step. If none is specified, this defaults to "step-", whereis the sequential number of the step (first step being number 1).

This identifier is useful when referencing command outputs in following steps. For example, if you set this to "my-step", following steps can reference the ${steps.my-step.outputs.*} key in the script or command fields.

Type
Required

string

No

steps[].command[]

A Garden command this step should run, followed by any required or optional arguments and flags.

Note that commands that are persistent—e.g. the dev command, commands with a watch flag set, the logs command with following enabled etc.—are not supported. In general, workflow steps should run to completion.

Global options like --env, --log-level etc. are currently not supported for built-in commands, since they are handled before the individual steps are run.

Type
Required

array[string]

No

Example:

steps:
  - command:
      - run
      - my-task

steps[].description

A description of the workflow step.

Type
Required

string

No

steps[].envVars

A map of environment variables to use when running script steps. Ignored for command steps.

Note: Environment variables provided here take precedence over any environment variables configured at the workflow level.

Type
Default
Required

object

{}

No

steps[].script

A bash script to run. Note that the host running the workflow must have bash installed and on path. It is considered to have run successfully if it returns an exit code of 0. Any other exit code signals an error, and the remainder of the workflow is aborted.

The script may include template strings, including references to previous steps.

Type
Required

string

No

steps[].skip

Set to true to skip this step. Use this with template conditionals to skip steps for certain environments or scenarios.

Type
Default
Required

boolean

false

No

Example:

steps:
  - skip: "${environment.name != 'prod'}"

steps[].when

If used, this step will be run under the following conditions (may use template strings):

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.

always: This step will always be run, regardless of whether any preceding steps have failed.

never: This step will always be ignored.

Type
Default
Required

string

"onSuccess"

No

steps[].continueOnError

Set to true to continue if the step errors.

Type
Default
Required

boolean

false

No

triggers[]

A list of triggers that determine when the workflow should be run, and which environment should be used (Garden Cloud only).

Type
Required

array[object]

No

triggers[].environment

The environment name (from your project configuration) to use for the workflow when matched by this trigger.

Type
Required

string

Yes

triggers[].namespace

The namespace to use for the workflow when matched by this trigger. Follows the namespacing setting used for this trigger's environment, as defined in your project's environment configs.

Type
Required

string

No

triggers[].events[]

Supported events:

pull-request, pull-request-closed, pull-request-merged, pull-request-opened, pull-request-reopened, pull-request-updated, push

Type
Required

array[string]

No

triggers[].branches[]

If specified, only run the workflow for branches matching one of these filters. These filters refer to the pull/merge request's head branch (e.g. my-feature-branch), not the base branch that the pull/merge request would be merged into if approved (e.g. main).

Type
Required

array[string]

No

triggers[].baseBranches[]

If specified, only run the workflow for pull/merge requests whose base branch matches one of these filters.

Type
Required

array[string]

No

triggers[].ignoreBranches[]

If specified, do not run the workflow for branches matching one of these filters. These filters refer to the pull/merge request's head branch (e.g. my-feature-branch), not the base branch that the pull/merge request would be merged into if approved (e.g. main).

Type
Required

array[string]

No

triggers[].ignoreBaseBranches[]

If specified, do not run the workflow for pull/merge requests whose base branch matches one of these filters.

Type
Required

array[string]

No

> path

> data

> secretName

> requests

> > cpu

> > memory

> limits

> > cpu

> > memory

> cpu

> memory

> name

> command

> description

> envVars

> script

> skip

> when

See the for details and examples.

> continueOnError

> environment

> namespace

> events

A list of that should trigger this workflow.

See the Garden Cloud documentation on for more details.

> branches

> baseBranches

> ignoreBranches

> ignoreBaseBranches

workflows guide
GitHub events
configuring workflows
Workflow
YAML Schema
Configuration keys
files
files
files
resources
resources
requests
resources
requests
resources
resources
limits
resources
limits
limits
limits
steps
steps
steps
steps
steps
steps
steps
steps
triggers
triggers
triggers
triggers
triggers
triggers
triggers