Gimlet manifest reference

You can control environment configuration with the Gimlet environment manifest file.

It pins down the release configuration to a target environment: the Helm chart to use, its version, and the configuration variables for a given environment.

The following example shows the configuration for an application's staging environment:

# .gimlet/staging.yaml
app: frontend
env: staging
namespace: my-team
  name: onechart
  version: 0.32.0
  replicas: 2
    repository: myapp
    tag: 1.1.0
    tlsEnabled: true

You store Gimlet manifest files under the .gimlet/ folder of your application source code repository. One file per environment.

See how you can manage Gimlet manifests.

Field reference

Basic fields

  • app The name of the app. It is used as Kubernetes resource names so it must adhere those rules.

  • env The slug of the Gimlet environment to deploy to.

  • namespace The namespace to deploy this application to. Namespaces are an arbitrary grouping, your team probably has a preferred namespace structure that serve you well. At Gimlet, as a rule of thumb, we use the environment name as namespace. For this tutorial, follow this practice and set the namespace as staging.


Fields for policy based deploy.


Fields for automatically clean up deployed applications. Primarily used in cleaning up preview apps


The Helm chart to use as application template

Charts from Helm repositories

  name: onechart
  version: 0.38.0

Charts from git repos


The above snippet is an example how to access a Helm chart hosted in a public git repository.

For private git repos to work on Gimletd, make sure to integrate Gimletd with Github.

On your laptop, you can use an SSH based git url in the field to access a private git repo. If you have your SSH agent running, Gimlet CLI will be able to pull the chart.


The values that will be passed to the Helm.

Variable support

The Gimlet manifest resolves Golang templates in the gimlet manifest template step or in the server-side automated deploy workflows.

Supported variables

On the terminal

If you run gimlet manifest template on the terminal, or in a script, all the set environment variables will be resolved, plus the variables you set with the --vars flag.

# .gimlet/staging.yaml
app: myapp
env: staging
namespace: my-team
  name: onechart
  version: 0.10.0
  replicas: 1
    repository: myapp
    tag: "{{ .GIT_SHA }}"
    tlsEnabled: true

# ci.env

gimlet manifest template \
  -f .gimlet/staging.yaml \
  -o manifests.yaml \
  --vars ci.env

In automated workflows

In automated workflows, variables that are part of the released artifact are available in templating.

Artifacts are shipped by CI, and each shipper ships

  • all CI specific variables with prefix GITHUB and CIRCLE
  • all custom variables that you add in the shipper configuration
  • and the default set of variables that are available no matter which shipper you use.

The exact list of variables in an artifact

You can look into an artifact by gimlet artifact list -o json and locate the .vars field. Key-value pairs from this field are made available (case-sensitive) as variables in the Gimlet manifest.

Built-in variables

The commonly available variables made available by shippers are:

REPOThe owner and repository name.
OWNERThe repository owner's name.
BRANCHThe name of the Git branch currently being built.
TAGThe name of the git tag, if the current build is tagged.
SHAThe commit SHA that triggered the workflow.
ACTORThe name of the person or app that initiated the workflow.
EVENTThe name of the event that triggered the workflow.
JOBA unique identifier for the current job.

Policy-based releases

Gimlet supports branch and tag filters.

Both support wildcards and negated expressions

Tag pattern trigger example

+  tag: v*
+  event: tag

Triggers on v1, v2, v1.1 or any glob pattern that is supported by the project.

Branch pattern trigger example

+  branch: feature/*
+  event: push

Triggers on any commit pushed to a branch that is prefixed with feature/.

Negated branch trigger

+  branch: !main
+  event: push

Triggers on any commit pushed to a branch that is not main.

Supported events

GimletD supports push, tag and pr events.

It is mandatory to set either the branch or the event condition. If both are defined, the policy triggers only if both conditions are satisfied.

Function support

Since Gimlet manifests are Golang templates, functions can be used.

The available functions:

  • functions are available
  • a special sanitizieDNSName function, see source.

An advanced example showcasing the available functions and Golang templating options:

app: "{{ printf \"gimlet-dashboard-%s\" .BRANCH | sanitizeDNSName }}"
env: preview
namespace: preview
  name: onechart
  version: 0.35.0
    annotations: nginx letsencrypt
    host: "{{ trunc 40 (printf \"gimlet-dashboard-%s\" .GITHUB_BRANCH) | sanitizeDNSName }}"
  • the app name is appended with the branch name, which is then sanitized to be a DNS name. This way preview app names are valid Kubernetes identifiers.
  • the host follows a simlar approach, but it also truncates the preview app name to 40 characters, to accomodate the company domain name.


The Gimlet manifest is able to apply Kustomize StrategicMergePatches and Json6902Patches, plus add plain Kuberenetes manifests. See their usage.

Upgrading Flux