Deploy with Vetra Apps

How it works

An app links a GitHub repository to a production environment on Vetra. A GitHub Action in your repository builds the code, publishes your Powerhouse packages and (optionally) a front-end image, then asks Vetra to deploy those exact versions.

Quickstart

1. 1

   Create an app and connect GitHub

   On vetra.io, install the Vetra Deploy GitHub App, pick your repository and choose the production branch. Vetra creates the production environment for you, or attaches one you already have.
2. 2

   Authorize the deploy identity

   Your app gets its own Renown identity. Approve it on Renown; for the next year GitHub Actions in that repository can deploy on your behalf, and nothing else can. vetra.io reminds you 30 days before it expires.
3. 3

   Add .github/workflows/vetra.yml

   Let Vetra open the setup pull request, or copy the workflow below. Merge it.
4. 4

   Push to main

   The action publishes your packages and deploys production. The run summary links to the live URLs.
5. 5

   Open a pull request

   A preview environment spins up for the PR and a comment links to it. Closing the PR removes it.

The workflow

This is the file the setup pull request adds (and the one ph init scaffolds). Replace <APP_ID>with the id from your app's Settings tab; the app page shows the snippet with it filled in.

name: Vetra
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  id-token: write
  contents: read
concurrency:
  group: vetra-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
jobs:
  deploy:
    if: github.event.pull_request.head.repo.fork != true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: pnpm }
      - uses: powerhouse-inc/vetra-deploy-action@v1
        with:
          app-id: <APP_ID>

id-token: write lets the job request a GitHub OIDC token, which Renown exchanges for a short-lived deploy token. No secrets need to be stored in the repository.

Inputs

Outputs

Monorepos

By default the action publishes the package at the repository root. In a monorepo, list every package directory to publish with package-dirs. Each one is packed with pnpm pack, so workspace:* and catalog: dependencies resolve to real versions.

      - uses: powerhouse-inc/vetra-deploy-action@v1
        with:
          app-id: <APP_ID>
          package-dirs: |
            packages/document-models
            packages/editors

Every listed package is published by the same run and installed on the environment at exactly that version. Set package-dirs to an empty string for a front-end-only app.

Front-ends (FUSION)

A FUSION service is a Next.js front-end that runs next to the environment's Connect and Switchboard. Point the action at its Dockerfile: it builds the image, pushes cr.vetra.io/<app project>/<image>:sha-<12 hex>to your app's private registry project and deploys that tag.

      - uses: powerhouse-inc/vetra-deploy-action@v1
        with:
          app-id: <APP_ID>
          fusion-dockerfile: apps/frontend/Dockerfile
          fusion-image-name: frontend

Image contract

• output: 'standalone' in next.config. The server listens on PORT (3000) and / answers 2xx/3xx.
• Build every NEXT_PUBLIC_* variable with the placeholder value __NEXT_PUBLIC_<NAME>__. One image then serves every environment.
• Start through ph-fusion-entrypoint.sh (vendor it unchanged). At start it swaps each placeholder for the real value.
• Run as uid/gid 1000.
• Compare NEXT_PUBLIC_*flags at runtime, not at module scope, and don't call new URL(...) on them at import time: the placeholder is what the build sees.

FROM node:24-alpine AS build
WORKDIR /repo
RUN corepack enable
COPY . .
RUN pnpm install --frozen-lockfile
ENV NEXT_PUBLIC_SWITCHBOARD_URL=__NEXT_PUBLIC_SWITCHBOARD_URL__ \
    NEXT_PUBLIC_CONNECT_URL=__NEXT_PUBLIC_CONNECT_URL__ \
    NEXT_TELEMETRY_DISABLED=1
RUN pnpm --filter frontend build

FROM node:24-alpine
WORKDIR /app
COPY --from=build /repo/apps/frontend/.next/standalone ./
COPY --from=build /repo/apps/frontend/.next/static ./apps/frontend/.next/static
COPY --from=build /repo/apps/frontend/public ./apps/frontend/public
COPY ph-fusion-entrypoint.sh /ph-fusion-entrypoint.sh
USER 1000:1000
ENV FUSION_APP_DIR=/app PORT=3000 HOSTNAME=0.0.0.0 NODE_ENV=production
ENTRYPOINT ["/ph-fusion-entrypoint.sh"]
CMD ["node", "apps/frontend/server.js"]

Versions & dist-tags

The action derives the version from version in package.json (without any prerelease part) and never commits back to your repository.

Pull-request builds can only reach registry.dev.vetra.io and their own preview: a PR can never publish to the production registry or deploy production.

Preview environments

• One environment per open pull request, created on its first deploy.
• Slim by design: a small database without backups, the smallest service sizes, and packages from registry.dev.vetra.io. Data starts empty.
• Deleted when the pull request is closed or merged.
• At most 5 per app by default; at the limit the least recently deployed preview makes room. Previews idle for 7 daysare removed. Both are adjustable in the app's Settings.
• No secrets: previews get your front-end's non-secret variables only, which is also the safe default for untrusted branches.
• Pull requests from forksdon't get previews: GitHub withholds the OIDC token from fork workflows.

Rollback

Open your app's Deployments tab and choose Rollback on any earlier successful production deployment. Vetra re-applies its exact package versions and image tag as a new deployment. The next push to the production branch deploys over it again, so revert the bad commit too.

Troubleshooting