Shipping from GitHub Actions

Once your overlay works locally, you want every merge to reach your testers without anyone opening the dashboard, and a tested build to reach everyone with one click. This guide sets up two workflows: one that bundles your app and site when you push to main and releases them to a private beta channel, and one you run by hand to promote what’s on beta to stable.

This guide uses the Overlayed CLI 2.0 directly; there is no separate GitHub Action. For what bundles, releases and channels are, see Understanding Bundles.

How It Fits Together

overlayed bundle uploads your app and site as bundles, and the platform builds each one. With --release, it then releases them to a channel once they’re built.
A release puts a bundle on a channel, and builds there: an app release builds your installer, a site release deploys your site. When the app and site are released together, the app goes first and the site’s minimum app version is set to the new app version, so users never get a site that needs an app they don’t have yet.
Promoting releases the same bundle on another channel. stable gets exactly the bundle your testers ran on beta, built again for that channel.
Every command fails the job when something fails. A build or release that fails, is cancelled or times out exits 1, so a broken release stops the workflow instead of passing silently.

Set It Up

Create a private beta channel

Every application starts with a public stable channel. Create a private channel named beta on the channels page. Your backend decides who may update from it: see Private Channels.Leave auto-release on bundle off for beta: the workflow releases to it explicitly, and overlayed bundle --release refuses a channel that already releases every bundle by itself. Check stable too: with auto-release on there, every bundle this workflow uploads would also go straight to stable, skipping beta.

Create an API key

Open API keys in the dashboard and create a key scoped to your application, with these permissions:

Permission	Why
`application::asset_bundles::read`, `application::asset_bundles::write`	Upload bundles and follow their builds
`application::releases::read`, `application::releases::create`	Release and promote
`application::releases::update`	Publish, raise rollouts, cancel
`application::channels::read`	Find channels by name

Running overlayed login on your machine opens this page with exactly these permissions preselected.

Your role must hold a permission to give it to a key. Developers can’t create or update releases, so someone whose role can, such as an application owner, needs to create this key.

Store it in GitHub

In your repository, open Settings → Secrets and variables → Actions and add:

A secret named OVERLAYED_API_KEY, holding the key.
A variable named OVERLAYED_APPLICATION_ID, holding your application’s id (the applicationId in your overlayed.config.ts). It isn’t secret.

The CLI reads both from the environment. The workflows below give the key only to the step that runs overlayed: npm ci and your build run code from your dependencies, which has no business seeing a key that can release.

Release pushes to beta

Add this workflow. It builds your project, then bundles the app and site and releases them to beta, bumping the patch version of the latest beta release each time. Runs take turns: while one releases, the newest push waits. GitHub keeps only the newest waiting run, which is all beta needs, since it releases a main that includes the pushes before it.The checkout keeps no Git credentials (persist-credentials: false) and the job’s GITHUB_TOKEN can only read: npm ci and your build run your dependencies’ code, and nothing here pushes.

.github/workflows/release-beta.yml

name: Release to beta

on:
  push:
    branches: [main]

# One release at a time, shared with the promote workflow: two runs bumping the same version would collide, and a
# promotion mid-release could pair the new app with the old site
concurrency:
  group: overlayed-release
  cancel-in-progress: false

permissions:
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build

      - run: npm install --global @overlayed/cli@2

      - name: Bundle and release to beta
        env:
          OVERLAYED_API_KEY: ${{ secrets.OVERLAYED_API_KEY }}
          OVERLAYED_APPLICATION_ID: ${{ vars.OVERLAYED_APPLICATION_ID }}
        run: |
          overlayed bundle \
            --app "app-${{ github.run_number }}-${{ github.run_attempt }}" \
            --site "site-${{ github.run_number }}-${{ github.run_attempt }}" \
            --release beta \
            --release-version patch

npm ci comes before bundling: the CLI reads the installed @overlayed/app and @overlayed/electron versions from node_modules, and npm run build produces the files your overlayed.config.ts includes.
Without a terminal the CLI doesn’t prompt, so each bundle is named on the command line. The run number and attempt keep the names unique, including when you re-run a failed job.
The step waits for the builds and both releases, up to 15 minutes each, and fails if any of them fails.

Promote beta to stable on demand

Add a second workflow that you run from the Actions tab when beta looks good. It promotes beta’s newest published app and site to stable, app first.

.github/workflows/promote-stable.yml

name: Promote beta to stable

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Version on stable: patch, minor, major, or a version like 1.4.0"
        required: true
        default: patch

# The same group as release-beta.yml: a promotion waits for a beta release in progress
concurrency:
  group: overlayed-release
  cancel-in-progress: false

permissions:
  contents: read

jobs:
  promote:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    # Waits for approval only if the stable environment has required reviewers (see below)
    environment: stable
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm install --global @overlayed/cli@2

      - name: Promote to stable
        env:
          OVERLAYED_API_KEY: ${{ secrets.OVERLAYED_API_KEY }}
          OVERLAYED_APPLICATION_ID: ${{ vars.OVERLAYED_APPLICATION_ID }}
          VERSION: ${{ inputs.version }}
        run: overlayed releases promote "$VERSION" --from beta --type both --to stable

Both workflows share one concurrency group, so a promotion started while beta is releasing waits until that release finishes rather than promoting halfway through it. Waiting isn’t the same as succeeding: if a beta run released its app but not its site, beta’s newest site is still the previous one, so finish the site on beta before promoting. GitHub keeps one waiting run per group: if a push to main arrives while your promotion waits, it takes the promotion’s place, and you start the promotion again.Promoting needs no checkout and no overlayed.config.ts: OVERLAYED_APPLICATION_ID tells the CLI which application to work on. The version input goes through env: rather than straight into the script, so nothing typed into the form can run as a command.stable is public. In a terminal the CLI would ask before releasing there; in a workflow it goes ahead.

Require an approval for stable (optional)

environment: stable on its own only names a GitHub environment; GitHub creates it unprotected, and the job starts at once. To make every promotion wait for a person, open Settings → Environments, select (or create) stable, and add Required reviewers. The promote job then waits until one of them approves it.The approval gates this workflow, not the key: a key with release permissions can release to any channel of its application, including from the beta workflow. Keep the key to these workflows, and review changes to them as you would a release.

Choosing Versions

Every release needs a version, and it must be higher than the channel’s latest release of the same type.

Bump each time
From a git tag
Separate app and site versions

--release-version patch (or minor, major) bumps the channel’s latest release of each type, so the app and site each count up on their own. Nothing to keep in sync, which suits a channel that gets every merge.

Release when you push a tag such as v1.4.0, using the tag as the version for both:

.github/workflows/release-beta.yml

on:
  push:
    tags: ["v*"]

# …
      - name: Bundle and release to beta
        env:
          OVERLAYED_API_KEY: ${{ secrets.OVERLAYED_API_KEY }}
          OVERLAYED_APPLICATION_ID: ${{ vars.OVERLAYED_APPLICATION_ID }}
        run: |
          overlayed bundle \
            --app "app-$GITHUB_REF_NAME-$GITHUB_RUN_ATTEMPT" --site "site-$GITHUB_REF_NAME-$GITHUB_RUN_ATTEMPT" \
            --release beta --release-version "${GITHUB_REF_NAME#v}"

--app-release-version and --site-release-version give each its own, e.g. when your site is versioned independently:

overlayed bundle --app "app-$GITHUB_RUN_NUMBER-$GITHUB_RUN_ATTEMPT" \
	--site "site-$GITHUB_RUN_NUMBER-$GITHUB_RUN_ATTEMPT" --release beta \
	--app-release-version patch --site-release-version 3.2.0

releases promote takes --app-version and --site-version the same way.

Rolling Out Gradually

By default a release uses its channel’s default rollout duration if the channel has one (set it on the channel), rising from 0% to 100% of users over that time. A channel without one releases to everyone at once. To choose per release, add a release option:

# 10% of stable users now
overlayed releases promote "$VERSION" --from beta --type both --to stable --rollout 10

# Later, from another run of a workflow: raise it (a published release's rollout only goes up)
overlayed releases rollout <release-id> 50

Using the Results

Add the global --json flag and a command prints only its result on stdout, with every id, status and dashboard link. This writes the promoted releases to the run’s summary page:

      - name: Promote to stable
        env:
          OVERLAYED_API_KEY: ${{ secrets.OVERLAYED_API_KEY }}
          OVERLAYED_APPLICATION_ID: ${{ vars.OVERLAYED_APPLICATION_ID }}
          VERSION: ${{ inputs.version }}
        run: |
          set +e
          overlayed --json releases promote "$VERSION" --from beta --type both --to stable > promote.json
          status=$?
          jq -r '.releases[]? | "- \(.release.bundle.type) \(.release.version): \(.release.dashboard_url)"' promote.json \
            >> "$GITHUB_STEP_SUMMARY"
          exit $status

A failed command still writes its JSON before exiting 1, so the ids of whatever it did create aren’t lost. GitHub stops a step at the first failing command, so the script above turns that off (set +e) to write the summary anyway, then exits with the CLI’s code. See JSON Output.

FAQ

The job fails with 'No terminal to prompt in'

A command needed an answer it would normally ask for. For overlayed bundle, name each bundle (--app <name>, --site <name>) and say which to bundle; for overlayed login, don’t run it in CI at all: OVERLAYED_API_KEY replaces it.

The release is refused: 'isn't higher than the latest release'

Another run released first, or the version you passed is already behind. Use a bump (patch) or a higher version. The concurrency block in the workflows above keeps two runs from racing for the same version.

The release is refused because the channel is public

Your application either doesn’t allow releases to public channels, or requires releases there to be drafts for review. The error says which. For draft review, add --draft; the release then waits as a draft instead of going live.

'Your API key is missing a permission'

The error lists the missing permission. Create a key that has it (see the table above) and update the OVERLAYED_API_KEY secret. API keys also expire: when a working workflow starts failing to authenticate, check the key’s expiry in the dashboard.

The app was released but the site wasn't

The command fails and names the app release that went out. If the site’s release was refused, failed or was cancelled, it also prints the overlayed releases create command that releases the site on its own, with the right minimum app version: fix the cause it reports, then run that command. If the wait gave up while the site was still building, the site release exists and holds its version: follow it with overlayed releases wait <id>, using the site release’s id printed above the error, instead.

How do I pull a bad release?

overlayed releases cancel <release-id> cancels a release that is still building, or revokes one that is live. After a revoke, users fall back to the previous release on the channel.

Can I release only the site?

Yes: bundle with --site alone. If the new site needs a newer app, add --min-app-version so users on older apps keep the old site. See Safe Site Releases.

My project is in a monorepo

The CLI finds overlayed.config.ts in the current directory or a parent, or up to three directories below it. Run the steps from your app’s package (working-directory:) if it’s deeper than that. See Config File Lookup. If the lockfile isn’t at the repository root, also point actions/setup-node at it with cache-dependency-path (e.g. apps/overlay/package-lock.json), or its npm cache step fails.

The step gives up while a build is still running

The CLI waits 15 minutes for each build or release by default, then fails. The build carries on on the server. Set OVERLAYED_WAIT_TIMEOUT (in seconds) in env: to wait longer. The limit applies to each wait, and they run one after another: bundle --release waits on the bundle builds, then the app release, then the site release, and promote --type both on the app, then the site. Keep the job’s timeout-minutes above all of them together, or GitHub can stop the job between the app and the site.

Next Steps

CLI Reference

Every command, option, exit code and JSON result.

Understanding Bundles

Bundles, channels and releases, and what each release builds.

Private Channels

Give your testers early builds.

App Updates

How installed apps pick up a new release.

​How It Fits Together

​Set It Up

​Choosing Versions

​Rolling Out Gradually

​Using the Results

​FAQ

​Next Steps

CLI Reference

Understanding Bundles

Private Channels

App Updates

How It Fits Together

Set It Up

Choosing Versions

Rolling Out Gradually

Using the Results

FAQ

Next Steps