Upload builds from CI/CD

How a CI upload works

A CI job builds your app, then uploads the output folder with an app-specific API key. Omnihorn stores it as a new build, scans and verifies every file, and signs the manifest. Once the build is active, it is assigned to the channel you named in the workflow and to every channel that follows the pushed branch.

Each CI build remembers its branch or tag, commit, commit message, who pushed it and a link to the CI run. The Builds tab shows the branch and short commit next to every such build. Files that were already uploaded in an earlier build are not uploaded again.

API keys

Create keys on the app’s CI/CD tab with Create key. A key starts with nk_ and is shown once, so copy it straight into a CI secret.

• A key belongs to one app. It can publish builds to that app, to any channel it names, and to every channel that follows the branch it reports.
• A key cannot read other apps, other keys or billing.
• An app can have 10 active keys. Revoking a key takes effect on the very next request.
• One key allows 60 requests a minute. Use one key per repository.

Set up GitHub Actions

1. 1

   Create a key

   In Omnihorn, open your app, then the CI/CD tab, and choose Create key. Copy the key.

2. 2

   Store it as a repository secret

   In GitHub, open the repository, then Settings, Secrets and variables, Actions, New repository secret. Name it OMNIHORN_API_KEY and paste the key.

3. 3

   Add the workflow

   Copy the workflow from the CI/CD tab into .github/workflows/release.yml, or use the one below.

4. 4

   Point it at your build output

   Replace the build step with your own build command. Make sure the files end up in the folder you pass as path, here ./dist.

5. 5

   Push and read the job summary

   Push to a branch the branches: filter matches. The job summary shows the version, the branch and what happened to each channel.

name: "Release my app"

on:
  push:
    branches: [main, 'release/**']

jobs:
  release:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      # Build your app here so that its files end up in ./dist
      - name: Build
        run: echo "Replace this step with your build command"

      - uses: Ivorn-Technologies/upload-build@v1
        with:
          api-key: ${{ secrets.OMNIHORN_API_KEY }}
          path: ./dist

Inputs and outputs

The step fails with exit code 1 when the upload fails, the build fails verification, or the build is deleted before the step finishes. The message names the file or the step.

Branch channels and following a branch

A channel can follow a branch. Open the channel on the Channels tab and set the Follow a branch card to an exact name such as main, or to a pattern where * matches anything, including /. The pattern release/* matches release/1.0 and release/1.0/hotfix. Separate several branches with commas, for example main,master. The first channel of a new app already follows main,master, so the first push from your default branch lands there without any setup. Each build from a matching branch is assigned to the channel once it is active.

A push to a branch that no channel follows creates a channel for it. The channel is named after the branch (feature/Login becomes feature-login), it is private, so installers need a token or password, and it follows that branch. Hand its token to testers from the channel page. To keep all feature branches on one channel instead, create a channel such as preview that follows feature/*.

• Your plan’s channel limit applies. At the limit the build is still created, no channel is, and the job summary says so. See pricing.
• Turn branch channels off for one workflow with create-branch-channel: false.
• Naming a channel with the channel input also stops a separate channel being created for that branch.
• A following channel never moves to a lower build number, so parallel jobs of the same branch cannot roll it back.
• You can still assign an older build by hand to roll back. The next matching push replaces it.

      - uses: Ivorn-Technologies/upload-build@v1
        if: github.ref == 'refs/heads/main'
        with:
          api-key: ${{ secrets.OMNIHORN_API_KEY }}
          path: ./dist
          channel: production

Tags and release versions

A tag build creates no branch channel and follows nothing. Name a channel with the channel input to ship it. The example below turns the tag v1.4.0 into the base version 1.4.0; Omnihorn appends +build.N.

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

jobs:
  release:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: echo "Replace this step with your build command"
      - id: version
        shell: bash
        run: echo "value=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
      - uses: Ivorn-Technologies/upload-build@v1
        with:
          api-key: ${{ secrets.OMNIHORN_API_KEY }}
          path: ./dist
          version: ${{ steps.version.outputs.value }}
          channel: production

Several apps in one repository

Create one key per app and store each as its own secret. A matrix job then picks the right secret for each app. Parallel jobs that upload to the same app are fine too: each build gets its own number.

jobs:
  release:
    runs-on: windows-latest
    strategy:
      matrix:
        include:
          - app: editor
            key: OMNIHORN_API_KEY_EDITOR
          - app: viewer
            key: OMNIHORN_API_KEY_VIEWER
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: echo "Build ${{ matrix.app }} into dist/${{ matrix.app }}"
      - uses: Ivorn-Technologies/upload-build@v1
        with:
          api-key: ${{ secrets[matrix.key] }}
          path: dist/${{ matrix.app }}

GitLab and other CI systems

The same upload runs as a command-line tool on Node 20.10 or later. Download dist/cli.js from the action repository and give the job the key as the environment variable OMNIHORN_API_KEY. Run it with --help to see every option.

release:
  image: node:22
  rules:
    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^release\//
  script:
    - ./build.sh   # puts the app into ./dist
    - curl -fsSL https://raw.githubusercontent.com/Ivorn-Technologies/upload-build/v1/dist/cli.js -o omnihorn-upload.js
    - node omnihorn-upload.js --path ./dist
# OMNIHORN_API_KEY is a masked CI/CD variable (Settings → CI/CD → Variables);
# GitLab passes it to the job as an environment variable.

On GitLab CI the branch, tag, commit, title, user and pipeline URL are read from GitLab’s own variables. On any other CI, pass the branch (or tag) and the commit as options. Store the key as a secret variable named OMNIHORN_API_KEY in each of them.

node omnihorn-upload.js --path ./dist --provider other --branch "$BRANCH" --commit "$SHA"

pipelines:
  branches:
    main:
      - step:
          image: node:22
          script:
            - ./build.sh   # puts the app into ./dist
            - curl -fsSL https://raw.githubusercontent.com/Ivorn-Technologies/upload-build/v1/dist/cli.js -o omnihorn-upload.js
            - node omnihorn-upload.js --path ./dist --provider other --branch "$BITBUCKET_BRANCH" --commit "$BITBUCKET_COMMIT"

trigger:
  branches:
    include: [main, release/*]

pool:
  vmImage: ubuntu-latest

steps:
  - script: ./build.sh   # puts the app into ./dist
    displayName: Build
  - script: |
      curl -fsSL https://raw.githubusercontent.com/Ivorn-Technologies/upload-build/v1/dist/cli.js -o omnihorn-upload.js
      node omnihorn-upload.js --path ./dist --provider other --branch "${BUILD_SOURCEBRANCH#refs/heads/}" --commit "$BUILD_SOURCEVERSION"
    displayName: Upload to Omnihorn
    env:
      OMNIHORN_API_KEY: $(OMNIHORN_API_KEY)   # a secret variable must be mapped explicitly

version: 2.1

jobs:
  release:
    docker:
      - image: cimg/node:22.0
    steps:
      - checkout
      - run: ./build.sh   # puts the app into ./dist
      - run: |
          curl -fsSL https://raw.githubusercontent.com/Ivorn-Technologies/upload-build/v1/dist/cli.js -o omnihorn-upload.js
          node omnihorn-upload.js --path ./dist --provider other --branch "$CIRCLE_BRANCH" --commit "$CIRCLE_SHA1"

workflows:
  release:
    jobs:
      - release:
          filters:
            branches:
              only: [main, /release\/.*/]

pipeline {
  agent { docker { image 'node:22' } }
  environment {
    OMNIHORN_API_KEY = credentials('omnihorn-api-key')   // a "secret text" credential
  }
  stages {
    stage('Build') {
      steps { sh './build.sh' }   // puts the app into ./dist
    }
    stage('Upload') {
      when { anyOf { branch 'main'; branch 'release/*' } }
      steps {
        sh 'curl -fsSL https://raw.githubusercontent.com/Ivorn-Technologies/upload-build/v1/dist/cli.js -o omnihorn-upload.js'
        sh 'node omnihorn-upload.js --path ./dist --provider other --branch "$BRANCH_NAME" --commit "$GIT_COMMIT"'
      }
    }
  }
}

Keeping keys safe

• Keep the key in a secret and never print it. The upload sends it only in an HTTP header to the Omnihorn API, never to storage or in a URL, and never logs it.
• Pull requests from forks get no secrets. The upload is then skipped with a notice and the step succeeds, so forks do not fail your checks.
• Branch channels are private, so a build of an unfinished branch is not open to everyone.
• To rotate a key, create a new one, update the secret, then revoke the old one.
• If a key leaks, revoke it at once, then check the Builds and Channels tabs. A leaked key can publish builds to one app.

Troubleshooting

More cases are on the troubleshooting page.