Description of Release GitOps workflow

You can use the Release UI to manage your Application Template, Environment Variables files, and environment configurations. But Release also supports managing these configuration files in your Git repository.

If your code and its Release configuration file are in the same branch of your Git repository, GitOps gives you concise management and version control of files.

Because of Git's branch-based workflow, GitOps is limited to one environment per branch.

  • If you'd like to have different environments (for example, staging and production environments with different resource allocation) coming from one master branch, we recommend you create a separate branch for each environment.

  • If you have multiple environments in the same branch, we recommend you use our UI.


We strongly encourage you to integrate your GitOps workflow with our Release CLI. You can initialize the correct GitOps files and validate they are correct before merging, which is very highly recommended to avoid syntax errors and possible broken deployments.

In order to use GitOps with Release, you'll need to:

  • Contact to enable GitOps for your account. GitOps is enabled for your whole account by default, but you can opt to enable GitOps per application and manage other applications using the Release UI.

  • We strongly encourage you to make sure you use secret references from one of our supported vaults.

  • Add these two lines to your .release.yaml file:

    application_template: .release/application_template.yaml
    environment_variables: .release/environment_variables.yaml
  • Check the application_template.yaml and environment_variables.yaml files in to your .release directory.

Release configuration relationships

Here's a simplified diagram of Release configuration relationships:

When you create an application, Release automatically creates a default Application Template and a default Environment Variables file. These files can be modified to include your application specifics.

Each time you create an environment for your application, Release will configure it using the Application Template and environment variables.

No configuration for any environment is stored in GitOps.

When you make changes to either the Application Template or the Environment Variables file, a new environment configuration is created and deployed.

Immutability, Updates, and Overrides

If you have GitOps enabled, any changes you make to the configuration files are only updated from your repo, and no longer from the Release UI. It is still possible to update the configurations manually, but the next push from your repository will override the manual updates. There are a few exceptions noted below.

Certain attributes cannot be updated with GitOps! Release will create new configurations for your environments, but the following attributes will not be overwritten: context, domain, hostnames, rules. These fields must be updated manually via the UI to prevent cross-environment changes during repository pushes.

You may have certain environment variables might likewise not want to be updated during the gitops workflow. You can exclude certain environment variables from being updated via GitOps (so they must also be manually edited via the UI) as shown in the following example:

  value: ephemeral
- key: REDIS_URI
  value: redis://redis

Whenever you modify and save an environment's configuration, the environment's configuration version number is incremented. The version number is made up of the version of the Application Template the environment was based on (the first digit), and the version of the environment-specific configuration currently deployed (the second digit). Changes to an environment's configuration will not change the first digit of an environment's version number. Saving an environment configuration file or environment variables file will change the second digit, incrementing the number by one.

In this diagram, you can see how different environments can be based on different Application Template versions:

GitOps workflow

When using GitOps, environment-specific configuration is automatically generated via a webhook processor that follows the workflow illustrated below.

With every push to your repository, Release runs this workflow to decide whether it should create new templates or configurations and whether it should deploy to any environments.

Pseudocode for the GitOps flow chart

  ##check if the Release GitOps files are modified
  if release_files_modified
    #get the template from the repo
    template_from_repo = app.template_from_repo

    #loop through every app for this repo that matches the branch
    repository.apps.with_branch(branch).each do |app|

      ##diff the template, if true, generate and save new templates
      if diff(template_from_repo, app.previous_template)

    #for every active environment for the repo that matches the branch
    repository.active_environments.with_branch(branch).each do |env|
      #transform app template to environment configuration
      env_config = transform_app_template_to_env_config(env)
      #if you want to deploy any matching envs, this setting must be true
      if should_deploy_active_envs_that_track_branch_with_config_change?

GitOps allows you to have different environment configurations in different branches that can be merged back to your main branch. In the same way you work on features and bugs in branches, you can try new configurations by making changes to your Application Template and environment variables in branches. When you merge back to your main branch, your configuration changes will be included. GitOps automatically pushes and deploys configuration changes to your Release environments.

Last updated