Orchestration

Promote changes from dev to production in a fixed order

Stacks set the order between environments, layered runs set the order inside one, and branch rules decide what merges where. When one pull request changes dev, staging, and production, Orchestration applies them in that order.

Stacks Layered runs Gitflow
Start free Read the docs

From dev to production

The order lives in config, not in a checklist

Stacks

Production waits for staging

Stacks group directories by environment and set rules between them. When one pull request changes all three, staging applies only after dev, and production only after staging. The dev stack can apply on its own after a successful plan.

Stacks →
.stategraph/config.yml
stacks: names: dev: tag_query: "dev in dir" rules: auto_apply: true staging: tag_query: "staging in dir" rules: apply_after: [dev] production: tag_query: "production in dir" rules: apply_after: [staging]

Illustrative. The rules apply when a pull request changes more than one stack.

Layers

Network first, then the database, then the app

Inside an environment, depends_on orders directories into layers. Each layer plans and applies only after the layers it depends on apply. A layer with no changes says so and hands off to the next one.

Layered runs →
.stategraph/config.yml
dirs: database: when_modified: depends_on: "dir:network" application: when_modified: depends_on: "dir:database"
stategraphbot
commented

Plans 👍

DirectoryWorkspaceResultCreateUpdateDelete
networkdefault✅100

This is a layered run with 2 layers remaining to apply. Layered runs require multiple rounds of planning and applying.

To apply all these changes, comment:

stategraph apply

Illustrative. The note follows the comment Orchestration posts on a layered run.

Apply after merge

The merge applies dev, a comment applies production

Apply after merge can be on for some directories and off for others. The dev directories apply the moment the pull request merges, and production still waits for a stategraph apply comment and its approvals.

Apply after merge →
.stategraph/config.yml
dirs: "dev/**": when_modified: autoapply: true "production/**": when_modified: autoapply: false

Illustrative. Apply requirements gate the comment. Branch protection gates the merge.

Gitflow

Each branch deploys its own environment

A dest_branch tag reads the target branch of each pull request, and workflows match it. Only dev merges into staging, and only staging and hotfix branches merge into main. A pull request outside those rules gets no runs.

Gitflow →
.stategraph/config.yml
tags: dest_branch: main: '^main$' staging: '^staging$' dev: '^dev$' destination_branches: - branch: main source_branches: - staging - hotfix/* - branch: staging source_branches: - dev

Illustrative. Workflows then match dest_branch:main and dest_branch:staging.

In the console

See where a change stands in every stack

The console lists the stacks of each open pull request in plan order and shows the live plan and apply state of each. A reviewer sees what applied and what waits without opening a CI log.

Stacks in the console →
A pull request in the Stategraph console: its stacks in plan order with their status, and the plan and apply runs A pull request in the Stategraph console: its stacks in plan order with their status, and the plan and apply runs

Real output. A pull request in the console, its stacks in plan order.

Write the promotion order down once

Put stacks and branch rules in .stategraph/config.yml, and every pull request follows them. Connect GitHub or GitLab to start.

Book a Demo Explore Orchestration