Skip to main content

CI Integration

Hosanna provides CI-safe commands, but it does not impose one universal pipeline file. Start from the application’s package.json, hosanna.json, engine requirement, and target projects. Run platform packaging only on workers that have the relevant SDK and signing access.

  1. Install: use the repository’s required Node version and npm ci.
  2. Authorize: provide HSC_LICENSE_KEY through a protected environment variable.
  3. Install sources: run npx hst license:status, npx hst sdk:install, and npx hst compiler:install.
  4. Restore CI secrets: run npx hst build-config:restore-secrets only in jobs that need those overlays.
  5. Validate: generate source, type-check, lint, and run unit/integration tests through project scripts.
  6. Build: use explicit platform, environment, target, app profile, and --non-interactive.
  7. Package and sign: isolate credentials by platform and release lane.
  8. Archive: retain the artifact, test report, source revision, resolved-source manifest, and checksums.

Example setup:

npm ci
npx hst license:status
npx hst sdk:install
npx hst compiler:install
npx hst build-config:restore-secrets --env prod --quiet

npm run generate
npm run lint
npm test

Use the exact scripts present in the app; do not copy a sample command that its package.json does not define.

Build Jobs​

Keep the target explicit and fail instead of prompting:

npx hst build web prod browser --non-interactive

npx hst build roku prod device \
  --hsc-project platforms/hsconfig-roku.prod.json \
  --non-interactive

npx hst build apple-tv prod device \
  --bundled \
  --non-interactive

npx hst build android-tv prod device \
  --bundled \
  --non-interactive

For app flavors, add --app <key> consistently to config resolution, build, tests, and packaging.

Secrets and Trust Boundaries​

Protected CI release boundary from secret-free pull-request validation through trusted signing and promotion of the same tested bytesProtected CI release boundary from secret-free pull-request validation through trusted signing and promotion of the same tested bytes

  • Store HSC_LICENSE_KEY, signing keys, provisioning credentials, store tokens, Roku passwords, and base64 overlays in protected CI variables.
  • Restrict signing jobs to protected branches/tags and trusted workers.
  • Do not expose secrets in command arguments when an environment variable is supported.
  • Do not cache restored secrets/, native signing state, or resolved secret-bearing config in a shared cache.
  • Review pull-request pipelines so untrusted code cannot print protected variables or upload forged artifacts.

build-config:restore-secrets accepts:

BUILD_CONFIG_SECRETS_<ENV>_BASE64
BUILD_CONFIG_PROFILE_SECRETS_<PROFILE>_BASE64

The variables decode to ignored JSON overlays. Keep normal endpoints and non-confidential behavior in tracked build-config/ so a release remains reviewable.

Tests and Device Labs​

Run fast browser regression suites on ordinary workers. Run native simulator suites on macOS/Android workers with the corresponding SDKs. Reserve physical-device and signing jobs for controlled runners.

The current sample repository exposes browser and native simulator scripts such as:

npm run test:ui:web
npm run test:ui:ios:sim
npm run test:ui:android:sim
npm run test:ui:androidtv:sim

Physical Roku runs require a reachable device and should not share a sideload target between concurrent jobs.

Reproducibility Checklist​

  • Pin dependencies with the lockfile and use npm ci.
  • Let hosanna.json pin the SDK/compiler distribution expected by the app.
  • Record HST, SDK, compiler, Node, platform SDK, and runner versions.
  • Generate timestamps and Git metadata once per release, before the build matrix fans out.
  • Build each artifact once; promote the tested bytes.
  • Publish checksums and retain test evidence with the artifact.
  • Make retries create a new build number unless the output is proven byte-for-byte identical.
Talk to us