Roll out a change

Sync the eks-simple example app’s built-in branch config, then plan and deploy a change across its installs.

This walkthrough builds on the eks-simple directory of the example-app-configs.

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 rolls a change out: plan each install group, approve, deploy. You can run a manual plan-only preview (or later a PR preview) before the fleet run; that is separate from the rollout and not required.

Prerequisites

• Finish Create an AWS EKS App Template first, or otherwise have the eks-simple app template in Nuon with at least one install on its main branch 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 install groups named stage and production, which select their installs by label.
• A labeled install, so it lands in the stage install group.
• A real fleet run you approve install group by install group (optionally a separate plan-only preview first via CLI, or later via PR).

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
default      = true

[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 as --branch-id to nuon branches commands.
• [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 install group’s plan waits for your approval before its deploy runs. Exactly one install group must set default = true (here, production); that install group catches installs that match no other selector.
• [install_groups.label_selector] picks each install group’s installs by label. An install labeled env = "stage" is in the stage install group; one labeled env = "prod" is in production. Nothing is hard-coded to a particular install, so adding a customer to an install group is a matter of labeling it.

Label your install

The stage install 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"
app_branch = "main"

[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 app or branch sync:

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

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

Sync the branch

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 branches sync --file branch.toml --confirm

This creates the main branch in your org with the stage and production install groups. The first sync also starts an app branch run that fetches the tracked ref, syncs the app config, and builds OCI artifacts for components and the sandbox (when configured). With no installs on the branch yet, that run stops after the build. Later syncs only update branch settings; shipping config through install groups is a fleet run from a push or nuon branches trigger (below).

New apps use app branches. nuon branches sync is how you create and update branch settings. nuon apps sync still works for apps that are not on app branches yet, and is deprecated.

Check what Nuon now has. You already selected the app, so branch commands do not need --app-id:

nuon apps list
nuon branches list

You should see one branch, main. In the dashboard, open the app and you will see the branch there too.

Preview a Change

Optional but recommended: preview a change before it merges into the tracked branch. A preview run is separate from the fleet rollout: start one manually with the CLI (below), or later from a pull request that uses [preview] defaults. You can skip to Deploy the Change and use nuon branches trigger instead.

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.

Branch runs always use a git-reachable config. Commit and push the change to a repository Nuon tracks, then preview that ref. With the stock public_repo pointing at nuonco/example-app-configs, you cannot push your edit there. Fork (or copy) the config into a repo you control, update the repo block, and sync (see Trigger From a Git Push). Once the commit is on a tracked repo:

nuon branches preview --branch-id main --git-ref <sha-or-branch> --mode plan-only

Nothing is applied to any install. The command prints the run’s ID and returns; watch the run in the dashboard, or with nuon branches runs --branch-id main, which opens the workflow TUI.

A preview run (CLI or pull request) does not create install group plan/deploy steps. It builds and plans against the preview target only (or build-only with no install). Fleet install groups run later from push, trigger, or another non-preview start.

Deploy the Change

After the change is on the tracked branch (merge or push to main), start a real rollout:

nuon branches trigger --branch-id main

If the branch’s [run] mode includes push (the default), a push to the tracked branch starts the same kind of run without a CLI step.

A real run walks these steps:

1. fetch commit: clone the repo at the run’s SHA
2. fetch app config: parse and sync the app config from that commit
3. building components and sandbox: rebuilds only what changed. The sandbox half needs sandbox builds for your org; without it, components only.
4. plan install group: stage: computes the diff for every install in the install group, then waits for you
5. deploy install group: stage: runs once you approve
6. plan install group: production: same for production
7. deploy install group: production: runs once you approve

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 install group deploys.

The run then stops at plan install group: production. An install group with no matching installs still pauses; Skip install group moves the run past it. By default the plan waits for approval. Set auto_approve_on_policies_passing = true on an install group to approve automatically when policy checks pass.

Watch runs from the CLI

nuon 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 the stock branch.toml tracks nuonco/example-app-configs, a repository you cannot push to. To preview your own edits and get push-triggered runs, point the branch at a repository of your own.

1. Push the config to your own repository

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

2. Connect it to Nuon

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

3. 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
   default      = true
   
   [install_groups.label_selector]
   env = "prod"
   
4. Sync the branch file, then push it

   nuon branches sync --file branch.toml --confirm
   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.

5. Open a pull request

   Stock eks-simple has no [preview] block. Add one with a preview target (for example label_selector or install_name), sync the branch, then open a pull request against main with a config change. Nuon starts a preview from those defaults (usually plan-only) and posts a comment headed ## Nuon Preview plus the branch’s name (not the app’s), with a table of what changed, plus a commit status named nuon/<org>/<app>/main preview (plan-only) linked to the preview run. Push another commit and the same comment is updated in place. Without a preview target, automatic PR previews are skipped; use nuon branches preview instead (see Previews).

Inspect the History

Every config change to an install is recorded as an app config version. There is no dedicated CLI command for versions, diffs, or re-apply: on the install, open Configuration → App branch → Applied config history, or use 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.

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 install 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 in a branch file.

Webhooks

Have your own systems react to branch runs.