Cloud Workflows

Garden Cloud will automatically run workflows in your Garden projects when it receives matching GitHub/GitLab events. Below is a guide to adding triggers to your workflows for use with Garden Cloud.

For an introduction to workflows, see the workflows guide.

Workflow Runners

The workflow runners are ephemeral pods that are spun up in a dedicated workflow runner namespace. The container image used contains the Garden Core CLI, and supporting tools such as bash, git, the Google Cloud CLI, the AWS CLI, the Azure CLI and more.

By default, the workflow runner will have access to the same repositories as the GitHub App or GitLab user access token that was configured for Garden Cloud. This is useful if your project has remote sources that need to be cloned. If your workflows require cloning repositories that are not accessible by the GitHub App / GitLab access token, you'll need to manually configure git for that, e.g. in a workflow script step.

Choosing the Garden version

Garden Cloud will automatically use the latest stable Garden Cloud release appropriate for your Garden project. At the moment, Garden Cloud relies on the apiVersion field in your project configuration to make that decision.

apiVersion in project configuration	Garden CLI version in Garden Cloud
No apiVersion is specified in the project configuration	Latest stable Acorn release (0.12)
apiVersion: garden.io/v0	Latest stable Acorn release (0.12)
apiVersion: garden.io/v1	Latest stable Bonsai release (0.13)
apiVersion: garden.io/v2	Latest stable Cedar release (0.14)

To verify that a Garden version works with your Garden Cloud workflows and 1-click Preview Environments, you can set the target apiVersion in your project configuration (kind: Project) in a new git branch and push that branch. That way you can verify that your project is compatible with the Garden version, before you make the change in the main branch, to avoid impacting your development team.

To verify Garden Bonsai (0.13) set apiVersion: garden.io/v1, and to verify Garden Cedar (0.14) set apiVersion: garden.io/v2.

See also the Bonsai migration guide and Cedar migration guide.

Workflow Triggers

When a webhook event is received from your VCS provider (GitHub or GitLab), Garden Cloud will match it against the trigger specs in all workflow configs found in the repository.

The trigger spec's environment (and namespace, if specified) is the environment (as defined in your Garden project configuration) that will be used when the workflow is run by Garden Cloud.

The matching is based on three filters:

trigger.branches (and trigger.ignoreBranches)

An optional list of branch patterns (which may include wildcards).

If the event's Git branch matches one of the patterns in trigger.branches (or if no branch patterns are configured), it passes the branch filter.

trigger.ignoreBranches has the opposite effect—if an event's Git branch matches one of the filters there, it doesn't match the trigger.

For pull/merge requests, the Git branch used is 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).

Example:

kind: Workflow
---
triggers:
  - branches: [feature-*] # matches e.g. feature-foo
    ignoreBranches: [experimental-*]
    environment: staging

trigger.baseBranches

An optional list of base branch patterns (which may include wildcards).

This filter is only applied for pull/merge request events.

If pull/merge request's base branch matches one of the patterns in trigger.baseBranches (or if no base branch patterns are configured), it passes the base branch filter.

trigger.ignoreBaseBranches has the opposite effect—if the pull request's base branch matches one of the filters there, it doesn't match the trigger.

Example:

kind: Workflow
---
triggers:
  - baseBranches: [main]
    ignoreBaseBranches: [feature-*]
    environment: staging

trigger.events

An optional list of event types to match against. Currently, the following events are handled by Garden Cloud:

• push

  • This event matches whenever commits are pushed to a branch.

• pull-request-opened

• pull-request-reopened

• pull-request-updated

  • This event matches when commits are pushed to an open pull / merge request.

• pull-request

  • This event is a shorthand event that matches any of pull-request-opened, pull-request-reopened or pull-request-updated.

• pull-request-closed

  • This event matches whenever a pull request / merge request is closed (regardless of whether the pull request was merged).

  • The workflow will be run from the base branch (e.g. main).

• pull-request-merged

  • This event matches when a pull request / merge request is merged (but not when it is closed without merging).

  • The workflow will be run from the base branch (e.g. main).

The pull-request-closed event will run from the base branch that the pull/merge request was created from. This is because the pull/merge request's branch could have been deleted by a user before any triggered workflows are able to run (which requires cloning the repo).

Due to this, workflows that use this trigger will not work until they have been merged to the main branch.

A complete example

Below is a full example of how you might configure workflows for a CI/CD process.

In this setup, we run all the project's tests when a pull request is created or updated. We also deploy a preview environment so that the code reviewer can walk through the live application as they inspect the changes.

When the pull request is closed, we make sure to delete the preview environment.

Finally, if the pull request is merged, we deploy to the staging environment after we merge to the main branch.

kind: Workflow
name: run-tests
description: Runs unit and integration tests.
steps:
  - command: [test]
  - command: [delete, environment]
    when: always # Delete the test namespace regardless of whether tests passed.
triggers:
  - events: [pull-request]
    environment: ci

---
kind: Workflow
name: deploy-preview
description: Deploys a preview environment for code review.
steps:
  - command: [deploy]
triggers:
  - events: [pull-request]
    environment: preview

---
kind: Workflow
name: cleanup-preview
description: Deletes the preview environment's namespace when the pull request is closed.
steps:
  - command: [delete, environment]
triggers:
  - events: [pull-request-closed]
    environment: preview

---
kind: Workflow
name: deploy-to-staging
description: Deploy to staging when pushing to or merging into the main branch
triggers:
  - events: [push]
    branches: [main]
    environment: staging

Resource requests and limits for workflow runners

The resources field on workflow configs can be used to configure the resource requests and limits used when scheduling workflow runner pods for that workflow config.

For example:

kind: Workflow
name: run-tests
description: Runs unit and integration tests.
steps: ...
triggers: ...
resources:
  requests:
    cpu: "100" # 100 millicpu = 0.1 CPU
    memory: "200" # 200 MB
  limits:
    cpu: "600" # 600 millicpu = 0.6 CPU
    memory: "750" # 750 MB

See the Kubernetes documentation on container requests and limits for more information.