GitHub Actions

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 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.

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.

Trigger a branch run from your workflow

Grant the job permission to request an OIDC token by setting the id-token: write permission on the workflow. Then configure a job step to use the Nuon CLI action. The CLI will detect that it’s running in GitHub Actions and perform 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.4.1
        with:
          org_id: ${{ vars.nuon_org_id }}
          app_id: ${{ vars.nuon_app_id }}
          command: "apps 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.

Variations

--preview makes the run plan-only: every group is planned, nothing is applied, and you read the per-install diffs from the completed run:

command: "apps branches trigger --branch-id main --no-wait --preview"

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

command: "apps 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 --yes"

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.

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.4.1
  with:
    api_token: ${{ secrets.NUON_API_TOKEN }}
    org_id: ${{ vars.nuon_org_id }}
    app_id: ${{ vars.nuon_app_id }}
    command: "apps 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.

Connect Your App

Install with a Customer

Day 2 Operations

Integrations

Advanced

Prerequisites

Using OIDC

Trigger a branch run from your workflow

Variations

Further usage

Action inputs

Using static API tokens

Next steps

Configure app branches

How app branches work

OIDC federation

Webhooks

​Prerequisites

​Using OIDC

​Trigger a branch run from your workflow

​Variations

​Further usage

​Action inputs

​Using static API tokens

​Next steps

Configure app branches

How app branches work

OIDC federation

Webhooks

Prerequisites

Using OIDC

Trigger a branch run from your workflow

Variations

Further usage

Action inputs

Using static API tokens

Next steps