GitHub Actions

Integrate with Nuon from your GitHub Actions workflows.

If you need to integrate with Nuon from your GitHub Actions workflows, we recommend using our official CLI action. This will handle installing the CLI and authenticating with Nuon for you, making it easy to run any CLI command as a GitHub Actions step. This guide walks through a common use case: triggering an app branch run from a repo where you do not have webhook permissions.

Prerequisites

• An app template with a branch configured and synced. See the app branches guide for details.
• Org admin access, to create the trust policy or API token the workflow authenticates with. See Authentication.

Trigger a branch run from your workflow

Configure a job step to use the Nuon CLI action. The example authenticates with OIDC, so the job needs the id-token: write permission; the CLI detects that it’s running in GitHub Actions and performs the token exchange automatically.

.github/workflows/rollout.yaml

on:
  push:
    branches:
      - main

permissions:
  contents: read
  id-token: write

jobs:
  rollout:
    runs-on: ubuntu-latest
    name: Roll out
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run your tests
        run: make test

      - name: Trigger branch run
        uses: nuonco/actions-nuon@v0.5.0
        with:
          org_id: ${{ vars.nuon_org_id }}
          app_id: ${{ vars.nuon_app_id }}
          command: "branches trigger --branch-id main --no-wait"

--no-wait will tell the CLI to return as soon as the App Branch run has been successfully created, allowing the GitHub Actions workflow to complete. Depending on how your App Branch is configured, there may still be manual approvals required in the workflows that are triggered.

Trigger a specific tag, commit, or pull request

actions-nuon also ships one action per run type. Each wraps nuon branches trigger --run-type:

Action	Equivalent CLI command
nuonco/actions-nuon/branches/trigger/tag	nuon branches trigger --run-type tag
nuonco/actions-nuon/branches/trigger/commit	nuon branches trigger --run-type commit
nuonco/actions-nuon/branches/trigger/pr	nuon branches trigger --run-type pr
nuonco/actions-nuon/branches/preview/pr	nuon branches preview --pr-number
nuonco/actions-nuon/branches/preview/git-ref	nuon branches preview --git-ref

For example, roll out each GitHub release once your own release workflow publishes it:

.github/workflows/nuon-release.yaml

on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  rollout:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger branch run for the release tag
        uses: nuonco/actions-nuon/branches/trigger/tag@v0.5.0
        with:
          org_id: ${{ vars.nuon_org_id }}
          app_id: ${{ vars.nuon_app_id }}
          branch_id: production
          tag: ${{ github.event.release.tag_name }}

A release run’s OIDC token carries the tag ref as its subject (repo:acme/app:ref:refs/tags/<tag>), so the trust policy needs a sub condition that matches tag refs as well as main. See claim matching.

Trigger actions take tag, sha, or pr_number. Preview actions take pr_number or git_ref, plus an optional mode (plan-only, apply, build-only). See the actions-nuon README for every input.

Variations

For a preview run (not a fleet rollout through install groups), use branches preview — for example against a committed ref or PR number:

command: "branches preview --branch-id main --git-ref my-feature --mode plan-only --no-wait"

--force on branches trigger rebuilds every component instead of only what changed since the previous run:

command: "branches trigger --branch-id main --no-wait --force"

Further usage

The command input takes any CLI command, so the same action covers whatever else your pipeline needs — for example, syncing install config files from your repo:

command: "installs sync -a ${{ vars.nuon_app_id }} -d ./installs --confirm --approve-all"

Action inputs

Input	Required	Description
org_id	yes	Your Nuon org ID.
command	no	The nuon command to run, without the leading nuon. Omit it to only install and configure the CLI.
app_id	no	Default app for commands that take one.
api_token	no	A static API token. Omit it to authenticate with OIDC.
api_url	no	The control plane API URL. Defaults to https://api.nuon.co.
oidc_audience	no	Audience for the OIDC token, if your trust policy’s audience differs from api_url.
nuon_version	no	CLI version to install. Defaults to the version your control plane reports.

For a self-hosted control plane, pass its API URL as the api_url input and use the same URL as the trust policy audience. If the two must differ, set oidc_audience to match the policy.

Authentication

The action authenticates with OIDC or with a static API token.

Using OIDC

We strongly recommend configuring GitHub Actions to authenticate with Nuon using OIDC, so no long-lived API tokens need to be stored in GitHub. Create a trust policy for the repository and its protected branch on the Manage OIDC page in the Dashboard. Select the repo you want to trust and the form will be filled out for you.

You can also use the CLI.

nuon orgs oidc-trust-policies create \
  --name github-actions \
  --issuer https://token.actions.githubusercontent.com \
  --audience https://api.nuon.co \
  --role org_admin \
  --ttl 900 \
  --claim sub=repo:acme/app:ref:refs/heads/main

Keep the sub condition limited to a protected branch and the --ttl short. The exchanged token only needs to outlive the one command it runs. See claim matching for other supported patterns.

Triggering an App Branch run currently requires org_admin permissions. We are in the process of adding more roles so such broad permissions are not required.

Using static API tokens

If you can’t use OIDC — for example, your organization disallows the id-token: write permission — you can authenticate using a long-lived API token.

Create the token and save it in a GitHub Actions secret named NUON_API_TOKEN.

nuon orgs api-tokens create --name github-actions --role org_admin

Then configure it on the workflow job step. The id-token: write permission is not required if you are using a token.

- name: Trigger branch run
  uses: nuonco/actions-nuon@v0.5.0
  with:
    api_token: ${{ secrets.NUON_API_TOKEN }}
    org_id: ${{ vars.nuon_org_id }}
    app_id: ${{ vars.nuon_app_id }}
    command: "branches trigger --branch-id main --no-wait"

When using static tokens, we strongly recommend rotating them as frequently as is practical.

Next steps

Configure app branches

Write the branch config, group your installs, and approve rollouts.

How app branches work

Run types, plan and approval flow, and install version history.

OIDC federation

Trust policies, claim matching, and other CI providers.

Webhooks

React to branch run events from your own systems.