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:
  1. 1
    Update Atmos to greater than version 1.180.0
  2. 2
    Pass the Atmos Pro Workspace ID by environment variable, see Getting Your Workspace ID
  3. 3
    Configure GitHub repository permissions, see Repository Permissions
Here's how to configure your workflow to use OIDC:
.github/workflows/affected-stacks.yaml
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 workflow_dispatch. This is what allows it to control deployment order and trigger the right workflows at the right time.
How it works
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 the github.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.

Checkout Complete ExampleConfigure Deployment Locking
Atmos StacksDeployment Locking