Configure GitHub Actions Workflows
In order for Atmos Pro to be able to dispatch your GitHub Actions workflows, you will need to make some small changes to your workflow. This section will walk you through how to update your GitHub Actions Workflow configuration.
This section assumes you are familiar with GitHub Actions workflows and have already been using them in your
organization. If you are new to GitHub Actions, please refer to the GitHub Actions
documentation for more information.
How it works
In order for Atmos Pro to be able to dispatch your GitHub Actions workflows, you will need to make some small changes to your existing workflows or create new workflows. The following is a list of the changes you will need to make.
Atmos Pro integrates GitHub's OpenID Connect (OIDC) authentication to securely obtain short-lived access tokens for interacting with the Atmos Pro API. This mechanism enhances security by eliminating the need for long-lived API tokens in CI/CD workflows.
How it works
To use OIDC authentication, you'll need to:
- 1Update Atmos to greater than version
1.180.0
- 2Pass the Atmos Pro Workspace ID by environment variable, see Getting Your Workspace ID
- 3Configure GitHub repository permissions, see Repository Permissions
Here's how to configure your workflow to use OIDC:
jobs:
affected:
name: Determine Affected Stacks
runs-on:
- "ubuntu-latest"
permissions:
id-token: write # Required for OIDC
contents: read # Required for checking out code
steps:
- name: Determine Affected Stacks
id: affected
uses: cloudposse/github-action-atmos-affected-stacks@v6
env:
ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }} # Your workspace ID from Atmos Pro
with:
atmos-version: ${{ vars.ATMOS_VERSION }} # >= 1.180.0
atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}
atmos-pro-upload: true
head-ref: ${{ github.event.pull_request.head.sha }}
All GitHub Actions workflows need a trigger—usually events like pull requests, pushes, or releases.
With Atmos Pro, it's different. Atmos Pro decides which workflows to run and when, using
How it works
workflow_dispatch
. This is what allows it to control deployment order and trigger the right workflows at the right time.To use a workflow with Atmos Pro, you will need configure the
on
trigger to include the workflow_dispatch
event. This will allow Atmos Pro to automatically trigger the workflow from the GitHub Actions API based on the events that you specify in the Atmos stack configuration.on:
workflow_dispatch:
Atmos passes some inputs to the workflow that the workflow needs to accept. This is how it knows which run ID, what stack, and so forth this dispatch is associated with.
How it works
To configure this, you will need to update the
inputs
section to include the required inputs. The inputs include two required
inputs plus the inputs that you specified in the Atmos Pro configuration. If the inputs do not match the required
inputs or the inputs you specified in the Atmos Pro configuration, GitHub will throw an error when we try to dispatch
the workflow.on:
workflow_dispatch:
inputs:
atmos_pro_run_id:
description: "Atmos Pro Run ID"
type: string
sha:
description: "Commit SHA"
type: string
component:
description: "Component"
required: true
type: string
stack:
description: "Stack"
required: true
type: string
atmos_pro_run_id
(required)- This is a required input for every Atmos Pro workflow. It is used to identify the workflow run that was dispatched by Atmos Pro. We need to track this in this manner because the GitHub API triggers workflow runs in an asynchronous manner and doesn't return a workflow_run_id to us when we call the API. This means that we can't rely on the
github.event.workflow_run.id
to identify the workflow run that was triggered so we need to create our own unique identifier. sha
(required)- This is also a required input for every Atmos Pro workflow. Since we are using
workflow_dispatch
as the method for running workflows, we don't have thegithub.event.pull_request.sha
or similar GitHub context to determine the SHA that should be checked out to run our workflow against, so Atmos Pro always passes the commit SHA which triggered the event as an input. component
(required)- The component to run the workflow on.
stack
(required)- The stack to run the workflow on.
When you open a pull request, Atmos Pro posts a status comment to track the deployment. This comment is tied to the
run-name
in your workflow.To ensure Atmos Pro can update the correct comment consistently, you should set a deterministic
run-name
in your workflow using the provided atmos_pro_run_id
from inputs.It should follow this format:
For
plan
workflows:run-name: plan ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}
For
apply
workflows:run-name: apply ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}
The workspace ID tells Atmos Pro which workspace a pull request or event belongs to. Since each workspace can manage multiple repositories, this ID is how Atmos Pro connects incoming GitHub events to the right context. It's also used during GitHub OIDC authentication to securely authorize CLI requests with the correct permissions.
How it works
GitHub does not automatically set environment variables unless you explicitly pass them with the
env
key. To pass it as an environment variable to the Atmos Pro GitHub Actions, you can add the following to your workflow:env:
ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }} # Your workspace ID from Atmos Pro
This environment variable is required for all Atmos Pro GitHub Actions workflows.
Now that you have configured your workflows to be dispatched by Atmos Pro, check out a complete example or configure deployment locking.
Ready to get started?
You've configured your workflows. Now, see it in action with a complete example or configure deployment locking.