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:
- 1Install Atmos using the
cloudposse/github-action-setup-atmos@v3action - 2
- 3Pass the Atmos Pro Workspace ID by environment variable, see Getting Your Workspace ID
- 4Configure 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
contents: read
checks: write
steps:
- name: Install Atmos
uses: cloudposse/github-action-setup-atmos@v3
with:
install-wrapper: false
atmos-version: ${{ vars.ATMOS_VERSION }}
- name: Determine Affected Stacks
shell: bash
env:
ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ATMOS_PROFILE: github
run: |
atmos describe affected \
--upload \
--identity=ex2/atmos \
--sha ${{ github.event.pull_request.base.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:
sha:
description: "Commit SHA"
type: string
component:
description: "Component"
required: true
type: string
stack:
description: "Stack"
required: true
type: stringsha(required)- Since we are using
workflow_dispatchas the method for running workflows, we don't have thegithub.event.pull_request.shaor 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.
Your GitHub Actions workflows need specific permissions to interact with Atmos Pro and post status checks. Add the following permissions block to your workflow jobs:
permissions:
id-token: write # Required for OIDC token generation
contents: read # Required for checking out code
checks: write # Required for creating/updating GitHub Checks
statuses: write # Required for posting commit status contextsThese permissions allow the workflow to authenticate via OIDC, read repository contents, and report check results back to pull requests.
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.
The
How it works
ATMOS_PROFILE environment variable tells Atmos which auth profile to load. Setting it to github loads the configuration from profiles/github/atmos.yaml, which contains the OIDC and authentication settings for GitHub Actions.GitHub does not automatically set environment variables unless you explicitly pass them with the
env key. To pass the required environment variables to your GitHub Actions workflow steps, add the following env block to each step that runs Atmos commands:env:
ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ATMOS_PROFILE: githubThis is a GitHub Actions workflow
env
block, not the Atmos
env configuration section. It sets environment variables for the runner so the Atmos CLI can authenticate with Atmos
Pro.These environment variables are required for all GitHub Actions workflow steps that call the Atmos CLI. The
GITHUB_TOKEN is automatically provided by GitHub Actions and is used by Atmos for interacting with the GitHub API.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.