This section assume you are familiar with Atmos and have already been using it to deploy your stacks. If you are new to Atmos, please refer to the Atmos documentation for more information.

Atmos Pro Settings

Each stack within your Atmos configuration file needs to be configured to use Atmos Pro. Luckily, Atmos' flexible structure with inheritance and mixins makes this easy to set reasonable defaults for every stack in your Atmos configuration and then override exceptions as needed.

# stacks/mixins/atmos-pro
settings:
  pro:
    enabled: true

Then, in your stack configuration, you can simply import the atmos-pro mixin to apply the settings to all stacks.

# stacks/orgs/ex1/plat/dev/us-east-2/demo.yaml
import:
  - orgs/ex1/plat/dev/_defaults
  - mixins/region/us-east-2
  - mixins/atmos-pro/default

Workflow Trigger Event Settings

In addition to telling Atmos Pro to dispatch the stack with the enabled: true setting, you also need to let Atmos Pro know which workflows you want to dispatch.

# stacks/mixins/atmos-pro
settings:
  pro:
    enabled: true
    pull_request: # when a pull request...
      opened: # is opened...
        workflows:
          atmos-terraform-plan.yaml: # dispatch the atmos-terraform-plan.yaml workflow...
            inputs: # with the following inputs
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      synchronize:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      reopened:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      merged:
        workflows:
          atmos-terraform-apply.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"

At first glance, this configuration looks verbose and seems that it could be simplified by using lists rather than maps in the YAML configuration. However, we use maps because we want to be able to deep merge the configuration using atmos, and lists do not support deep merging.

In practice, this configuration can be simplified by using YAML anchors. For example:

# stacks/mixins/atmos-pro
 
plan-wf-config: &plan-wf-config
  atmos-terraform-plan.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
 
apply-wf-config: &apply-wf-config
  atmos-terraform-apply.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
 
settings:
  pro:
    enabled: true
    pull_request:
      opened:
        workflows: *plan-wf-config
      synchronize:
        workflows: *plan-wf-config
      reopened:
        workflows: *plan-wf-config
      merged:
        workflows: *apply-wf-config

Github Events

As you can see from the example above, you can specify a map of GitHub events that will cause a workflow to run. The currently supported events are pull-request and release.

Activity Types

Next, you specify a list of the individual activity types you'd like to run a workflow for when they occur.

For pull_requests, you can specify the full list of supported activity types, plus merged, which is a special activity type we created to mean a pull request was closed and merged. You can also specify a list of triggers that specify Github "sub-events" to dispatch and the inputs to pass to the workflow.

For release, you can specify the full list of supported activity types.

Inputs Passed to Github Actions

The final piece of configuration is to specify the inputs that will be passed to the workflow. This is is a list of key/value pairs that will be passed to the workflow as inputs.

Since our example is using the atmos-terraform-plan.yaml and atmos-terraform-apply.yaml workflows, we need to pass the component, stack inputs to the workflows.

You can see that we are using Atmos template functions to dynamically extract the component and stack from the stack config.

Next Steps

Now that you've learned how to configure Atmos, let's take a look at how you can configure your Github Actions Workflow. To learn more about how to configure Atmos to support Atmos Pro, click the Configure Your Workflows link below.