A workflow dispatch is a GitHub Actions feature that lets you manually trigger a workflow run. You can start these workflows from the GitHub web interface or programmatically via the GitHub API. This is especially useful for workflows that need to run on demand, rather than automatically in response to repository events.

Native GitHub Actions let you trigger workflows based on events like pull requests and merges. But unlike with GitHub Actions, Atmos Pro can determine exactly what changed—and dispatch workflows in the correct order, waiting for dependencies to finish before moving on.

Atmos Pro uses workflow_dispatch to trigger these workflows via GitHub’s API and then waits for the results.

Atmos Pro doesn’t run your workflows. It just tells GitHub what to run, and when.

The workflows run entirely within your GitHub environment—on hosted or self-hosted runners—using your existing environments, controls, and security settings.

Workflow dispatches in Atmos Pro work by mapping GitHub events to specific workflows that should be executed. When a GitHub event occurs (such as a pull request being opened or merged), Atmos Pro automatically dispatches the appropriate workflows based on your configuration.

The configuration for workflow dispatches is defined in your Atmos stack configuration files, where you specify which GitHub events should trigger which workflows and what inputs should be passed to those workflows.

Atmos Pro supports mapping different GitHub events to workflows. The currently supported events are:

For each event type, you can specify which workflows should be dispatched and what inputs should be passed to them. For example, when a pull request is opened, you might want to run a Terraform plan workflow, and when it's merged, you might want to run a Terraform apply workflow.

Workflow dispatches can pass dynamic inputs to your GitHub Actions workflows. These inputs are typically extracted from your Atmos stack configuration using Atmos template functions.

This allows your workflows to be context-aware and automatically adapt to the specific stack and component being processed.

One of the key features of Atmos Pro is its ability to dispatch workflows in the correct order based on component dependencies. When multiple components are affected by a change, Atmos Pro analyzes the dependency graph defined in your Atmos configuration and dispatches workflows in the proper sequence.

For example, if you have a database component that depends on a VPC component, Atmos Pro will ensure the VPC workflow completes before dispatching the database workflow. This dependency management is handled automatically based on the settings.depends_on configuration in your Atmos stack files.

When Atmos Pro dispatches a workflow, it needs to know what command the workflow represents — is it a plan, apply, detect, or remediate? This determines the badge shown in the deployments view and enables filtering by command type.

Command detection follows a two-step process:

This means that even if a workflow has an ambiguous filename (like deploy.yaml), the command will be correctly identified once the workflow completes and Atmos reports back.

The workflow dispatch configuration is defined in your Atmos stack configuration files, typically in mixins that can be inherited across multiple stacks. This allows you to maintain consistent workflow dispatch behavior across your entire infrastructure while still allowing for stack-specific customizations when needed.

The configuration structure maps GitHub events to activity types, and then to specific workflows with their required inputs. This mapping is processed by Atmos Pro when GitHub events occur, ensuring that the right workflows are dispatched with the right parameters at the right time.

Now that you understand how workflow dispatches work, you can learn about configuring your Atmos stack files to define these mappings. The configuration process involves updating your Atmos configuration files to specify which events should trigger which workflows.

This feature is particularly useful for scenarios where you need to run deployments manually, such as for an emergency fix, a one-off task, or for testing changes in a development environment before promoting them to production.

By leveraging workflow dispatches, you gain the flexibility to control your deployment processes while still benefiting from the automation and repeatability of GitHub Actions.