Roll Out a Change with an App Branch

This walkthrough builds on the eks-simple directory of the example-app-configs repository, which now ships a branch.toml.

App branches turn a change to your app config into a single, reviewable rollout across your installs. eks-simple already ships its branch config. This walkthrough syncs it into your org and takes a change through it end to end: preview the diff, plan each deployment group, approve, deploy.

Prerequisites

Finish Create an AWS EKS App first, or otherwise have the eks-simple app synced to Nuon with at least one install that has finished provisioning.
The Nuon CLI, authenticated with nuon auth login and pointed at your org with nuon orgs select.
A clone of example-app-configs.

What You Will Create

An app branch named main in your org, created by syncing the branch config that ships in the eks-simple directory of the example repository.
Two deployment groups named stage and production, which select their installs by label.
A labeled install, so it lands in the stage group.
A plan-only preview run, and then a real run you approve group by group.

Review the Branch Config

`branch.toml`

The branch config is a single file at the root of the app config directory, alongside metadata.toml. eks-simple already includes it — open eks-simple/branch.toml in your clone and read it against what follows:

branch.toml

name = "main"

[public_repo]
directory = "eks-simple"
repo      = "nuonco/example-app-configs"
branch    = "main"

[[install_groups]]
name  = "stage"
order = 1

[install_groups.label_selector]
env = "stage"

[[install_groups]]
name  = "production"
order = 2

[install_groups.label_selector]
env = "prod"

Reading it top to bottom:

name = "main" is the branch’s name in Nuon. It comes from this key, not from the filename, and it is what you pass to nuon sync --branch.
[public_repo] is the repository the branch tracks. directory is the path to the app config inside that repo, so eks-simple here rather than ".". All three fields are required.
Two [[install_groups]] — stage first (order = 1), then production (order = 2). Lower order deploys first, and each group’s plan waits for your approval before its deploy runs.
[install_groups.label_selector] picks each group’s installs by label. An install labeled env = "stage" is in the stage group; one labeled env = "prod" is in production. Nothing is hard-coded to a particular install, so adding a customer to a group is a matter of labeling it.

Both groups use label_selector rather than install_names on purpose. Names are resolved to install IDs when you sync and an unknown name fails the whole sync, so a name-based group breaks in any org where that install does not exist. Label selectors re-evaluate on every run.

Label your install

The stage group is empty until an install carries env = "stage". Label the install you provisioned earlier:

nuon installs labels set --install-id <your-install-name-or-id> env=stage

Then confirm the selector matches it:

nuon installs list --labels env=stage

The example app also declares its CI installs as tracked config files, and sets the labels there instead:

installs/eks-simple-ci-stage.toml

#:schema https://api.nuon.co/v1/general/config-schema?type=install

name = "eks-simple-ci-stage"

[labels]
env = "stage"

approval_option = "approve-all"

[aws_account]
region = "us-east-1"

[[inputs]]
domain = "nuon.run"
sub_domain = "whoami"

Either route sets the same label. Install config files have their own sync command, separate from nuon apps sync:

nuon installs sync -a <your-app-id> -d installs/

Managing labels in the files means group membership is version-controlled along with everything else about the install.

Sync the app

From the eks-simple directory (start in the directory where you cloned example-app-configs):

cd example-app-configs/eks-simple
nuon apps select                 # no flags: pick eks-simple from the list
nuon apps sync

The sync creates the branch and its two deployment groups. Check what Nuon now has:

nuon apps list                   # prints each app's name and ID
nuon apps branches list --app-id <your-app-id>

Branch commands take the app ID (app...) — copy it from nuon apps list. Selecting the app with nuon apps select (no flags, pick from the list) stores it once, which is what lets the rest of this walkthrough drop --app-id from trigger and runs.

You should see one branch, main. In the dashboard, the app now has a Branches view showing the branch and its Deployment plan: stage, then production.

The eks-simple branch's deployment plan in the Nuon dashboard: a stage group selecting env=stage installs flowing into a production group selecting env=prod — The main branch's deployment plan after the sync: stage first, then production, each selecting installs by label.

Preview a Change

Before deploying anything, see what a change would do. Edit the sub_domain input default in inputs.toml (this is an excerpt — leave the rest of the file as it is):

inputs.toml (excerpt)

[[input]]
name         = "sub_domain"
description  = "The sub domain for the Whoami service"
default      = "hello"
display_name = "Sub Domain"
group        = "dns"

A changed default only shows up in the diff for installs that inherit it. An install that sets sub_domain explicitly (including eks-simple-ci-stage, whose config file pins it) shows an empty diff for this change. To see the diff on every install, change something unconditional instead, or remove the explicit value from your install first.

Then run a plan-only preview against your local files:

nuon sync --branch main --preview

This syncs the config in the current directory and triggers a plan-only run for it. Nothing is applied to any install. The command prints the run’s ID and returns; watch the run in the dashboard, or with nuon apps branches runs --app-id <your-app-id> --branch-id main, which opens the workflow TUI.

A manual plan-only run still walks the deployment groups: it creates each group’s plan install group and deploy install group step, but each approval gate auto-approves (“Auto-approved in plan-only mode”) and nothing is applied, so the run finishes on its own. Read the per-install diffs from the completed run. (A pull request preview behaves differently and never creates the group steps at all.)

nuon sync --branch runs against your local working directory, including uncommitted edits. That makes it the fast way to iterate on a change before you commit it. Note the flag lives on nuon sync, not nuon apps sync.

Run It for Real

Drop the --preview and the same command becomes a real rollout:

nuon sync --branch main

Or trigger a run from the branch’s committed config, with no local sync at all:

nuon apps branches trigger --branch-id main

Both walk the same deployment groups, but their first two steps differ, because nuon sync --branch hands Nuon a config it already built from your working directory while trigger fetches one from git:

Step	`nuon sync --branch main`	`nuon apps branches trigger`
1	`fetch commit (skipped)`	`fetch commit`
2	`fetch app config (skipped)`	`fetch app config`
3	`building components and sandbox`	`building components and sandbox`
4	`plan install group: stage`	`plan install group: stage`
5	`deploy install group: stage`	`deploy install group: stage`
6	`plan install group: production`	`plan install group: production`
7	`deploy install group: production`	`deploy install group: production`

From step 3 on they are identical:

building components and sandbox rebuilds only what changed.
each plan install group computes the diff for every install in the group and then waits for you.
each deploy install group runs once you approve the plan before it.

Approve the plan

The run pauses at plan install group: stage. In the diff, installs that inherit the default show sub_domain moving from whoami to hello; installs that pin sub_domain explicitly show no change for it (see the note in Preview a Change). Approve the plan and the group deploys. The run then stops at plan install group: production. A group with no matching installs still pauses; Skip install group moves the run past it.

Every group’s plan waits for an approval, from the dashboard or an API caller. There is no setting that auto-approves a deployment group.

Watch runs from the CLI

nuon apps branches runs --branch-id main

This lists the branch’s runs and opens the one you pick in the workflow TUI.

Trigger From a Git Push

So far every run has been triggered by hand, because branch.toml tracks nuonco/example-app-configs, a repository you cannot push to. To get the push-triggered behavior, point the branch at a repository of your own.

Push the config to your own repository

Fork example-app-configs, or copy the eks-simple directory into a repository you control.

Connect it to Nuon

Connect the Nuon GitHub App for your repository’s owner (see connecting a repository). This is what makes pull request previews possible. It is an org-level connection keyed on the owner, so it enables previews for any branch tracking a repo under that owner, whether the branch config uses [connected_repo] or [public_repo].

Update the repo block

Swap [public_repo] for [connected_repo], pointing at your repository and the directory the config lives in:

branch.toml

name = "main"

[connected_repo]
directory = "eks-simple"
repo      = "your-org/example-app-configs"
branch    = "main"

[[install_groups]]
name  = "stage"
order = 1

[install_groups.label_selector]
env = "stage"

[[install_groups]]
name  = "production"
order = 2

[install_groups.label_selector]
env = "prod"

Sync, then push

nuon apps sync
git commit -am "point app branch at my repo"
git push origin main

The push starts a run on its own. From here on, a commit to main is the trigger, with no CLI step in between.

Open a pull request

Open a pull request against main with a config change in it. Nuon runs a plan-only preview and posts a comment headed ## Nuon Preview — main (the branch’s name, not the app’s) with a table of what changed, plus a nuon/preview commit status. Push another commit and the same comment is updated in place.

Inspect the History

Every config change to an install is recorded as an app config version. Open the install in the dashboard and look at its Versions view, or list them over the API (create an API token in the dashboard’s org settings; the install ID comes from nuon installs list):

curl -H "Authorization: Bearer $NUON_API_TOKEN" \
  -H "X-Nuon-Org-ID: $NUON_ORG_ID" \
  "https://api.nuon.co/v1/installs/$INSTALL_ID/app-config-versions"

Any earlier version can be applied again, which is the path back if a change turns out badly. The guide walks through rolling back to a previous version.

Wrapping Up and Next Steps

You now have a git branch wired to a fleet: a change to the config produces a build, a diff per install, and an approval gate in front of each group. Where to go next:

Configure app branches

Multiple branches, label-driven groups, and the full command reference.

How app branches work

Run types, previews, and version history in depth.

Branch config reference

Every field on branch.toml.

Webhooks

Have your own systems react to branch runs.

​Prerequisites

​What You Will Create

​Review the Branch Config

​branch.toml

​Label your install

​Sync the app

​Preview a Change

​Run It for Real

​Approve the plan

​Watch runs from the CLI

​Trigger From a Git Push

​Inspect the History

​Wrapping Up and Next Steps

Configure app branches

How app branches work

Branch config reference

Webhooks

Prerequisites

What You Will Create

Review the Branch Config

`branch.toml`

Label your install

Sync the app

Preview a Change

Run It for Real

Approve the plan

Watch runs from the CLI

Trigger From a Git Push

Inspect the History

Wrapping Up and Next Steps