Upstream (Ingest)

Build, upload, and promote — getting artifacts from the build machine into HydraRelease.

What You'll Have

After completing the upstream phases, the pipeline has:

• A packaged build — the Unreal Engine project compiled and ready for distribution
• A registered build in HydraRelease — immutable, versioned, with a build number
• A staging release — latest.json pointing to the promoted build, ready for downstream consumption

Build machine                  HydraRelease
┌──────────────┐              ┌─────────────────────────────────────┐
│ UE Project   │──package──→  │ visit-flanders-main-experience/     │
│ + HydraUE    │              │   builds/                           │
└──────────────┘              │     1/ (build artifacts)            │
       │                      │   staging/                          │
       │  upload via           │     latest.json → build 1, v1.0.0  │
       └──Perforce/Transfer──→│                                     │
                              └─────────────────────────────────────┘

Downstream services (HydraExperienceLibrary, HydraCluster, hydrabody agents) read from latest.json to know what to deploy.

Phase 1: Build the Unreal Project

Component: HydraUnrealEngine (on the build machine) Type: Sequential — must complete before anything else

The build machine has an Unreal Engine project. The project can be sourced from Perforce, Git, or simply be local. HydraUnrealEngine wraps RunUAT to package it.

# On the Windows build machine
hydraunrealengine package MyProject.uproject \
  --platform Win64 \
  --config Shipping \
  --output C:\Builds\MyProject

HydraUnrealEngine runs preflight checks (Live Coding, Visual Studio, GameplayStateTree), then calls RunUAT. Output is a packaged build directory.

What to Verify

• Build completes without errors
• Output directory contains the packaged executable and assets
• SHA256 checksums can be computed for the output files

Active components: HydraUnrealEngine only — everything else is idle.

Phase 2: Upload the Build

Type: Sequential (follows Phase 1) — but the upload path has two parallel options

The build needs to get from the build machine to HydraRelease. Two paths:

Path A: Automated via Perforce + HydraPerforce

If the build machine submits the output to Perforce:

1. Developer/CI submits build to Perforce depot (e.g. //visitflanders/main/Builds/...)
2. HydraPerforce (running on the Perforce server) polls every 5 minutes
3. Detects new changelist, fetches files via p4 print
4. Uploads to HydraRelease via rsync
5. Calls POST /api/v1/builds on HydraRelease to register the build
6. Notifies HydraExperienceLibrary via POST /api/v1/builds/notify

Active components: Perforce server, HydraPerforce, HydraRelease

Path B: Manual via HydraTransfer or direct API

If not using Perforce:

1. Upload build files via HydraTransfer (web UI or API) for ad-hoc sharing
2. Or call POST /api/v1/builds on HydraRelease directly

hydrarelease build submit \
  --server https://releases.experiencenet.com \
  --project visit-flanders-main-experience \
  --uploaded-by ci-pipeline \
  --token $HYDRARELEASE_AUTH_TOKEN \
  experience.zip

What to Verify

hydrarelease build list --project visit-flanders-main-experience \
  --server https://releases.experiencenet.com

hydrarelease build show --project visit-flanders-main-experience --build 1 \
  --server https://releases.experiencenet.com

SSE event emitted: build.uploaded

Phase 3: Promote to Staging

Component: HydraRelease Type: Sequential (follows Phase 2)

The uploaded build is just a build — it is not deployed anywhere yet. Promotion makes it a release in a specific environment.

hydrarelease release promote \
  --server https://releases.experiencenet.com \
  --project visit-flanders-main-experience \
  --env staging \
  --build 1 \
  --version "1.0.0" \
  --notes "Initial staging release" \
  --token $HYDRARELEASE_AUTH_TOKEN

This:

1. Records the promotion in releases.yaml
2. Writes latest.json at /<project>/staging/latest.json with {"version":"1.0.0","build_number":1}
3. Tracks previous_build_number for future rollback
4. Emits release.promoted SSE event

What to Verify

hydrarelease release show \
  --project visit-flanders-main-experience --env staging \
  --server https://releases.experiencenet.com

curl https://releases.experiencenet.com/visit-flanders-main-experience/staging/latest.json

Rollback

hydrarelease release rollback \
  --project visit-flanders-main-experience --env staging \
  --server https://releases.experiencenet.com \
  --token $HYDRARELEASE_AUTH_TOKEN

This reverts to previous_build_number, writes a new latest.json, and triggers reprovisioning of all affected nodes.

SSE event emitted: release.promoted / release.rolled-back

Active components: HydraRelease only

Dashboard

The Upstream (Ingest) card on the hydrapipeline admin dashboard (/admin) shows two sub-sections:

• Build Pipelines — hydraapplepipeline and hydrapipelinerunnerapple (see runbook-build.md for their panels)
• Ingest — hydratransfer, hydraperforce, hydraunrealengine, hydraunrealengine-server

UE Jobs panel

When jobs_url and admin_token are set for hydraunrealengine-server in hydrapipeline's config, a collapsible UE Jobs panel appears inline under hydraunrealengine-server — shows the last packaging job with status, platform, config, started time, and a download link when the job completed with delivery.

The panel is hidden when no job has run since the server last started (status = idle). It appears after the first packaging job runs and persists until the server restarts.

Config fields in hydrapipeline's /var/lib/hydrapipeline/config.yaml:

- name: hydraunrealengine-server
  type: service
  url: https://hydraunrealengine.experiencenet.com
  health_url: https://hydraunrealengine.experiencenet.com/api/v1/health
  jobs_url: https://hydraunrealengine.experiencenet.com/api/v1/jobs
  admin_token: "<token>"
  group: upstream