Perforce Integration

Unreal Cloud connects to your Perforce server with a service account you create. Each project builds from one stream depot, and each preset picks a stream in it.

Before you connect

Allow Unreal Cloud's IP address

Everything Unreal Cloud sends to your server, from the dashboard's checks to the builders' syncs, comes from one address:

136.114.234.234

Allow it on your server's Perforce port (usually 1666) in your firewall. It's a reserved address and won't change.

Use SSL

Your server's address must start with ssl:, for example ssl:perforce.example.com:1666. Unicode and non-Unicode servers both work.

Create a service account

Create a dedicated user with read access to the depot you'll build. Read access is enough: Unreal Cloud never submits, and it can create and delete its own workspaces.

As a super user:

p4 user -f unrealcloud
p4 passwd unrealcloud

p4 passwd asks for the new password. Use a long random one, for example from openssl rand -base64 24.

Then give it read access to your depot in p4 protect, replacing YourDepot with its name. The username is up to you, as long as it matches:

read user unrealcloud * //YourDepot/...

Allow parallel syncs (recommended)

Builds sync over up to 8 connections at once when your server allows it, which is usually faster over long distances. As a super user:

p4 configure set net.parallel.max=8

Without it, builds still work, over a single connection.

Connecting a server

The fingerprint is pinned: if your server's certificate changes, Unreal Cloud refuses to connect rather than trusting a new one. After replacing a certificate on purpose, disconnect and connect again to confirm the new fingerprint.

Streams and presets

A preset's Stream is the stream it builds, like //YourDepot/main, and it can be changed for a single build when you trigger it.

Perforce presets are always Manual: builds start from the dashboard, or on every submit with a trigger. When a build starts, Unreal Cloud looks up the stream's latest submitted changelist, and the build syncs exactly that changelist, even if more are submitted before it starts. The changelist number is shown where GitHub builds show a commit.

Perforce has nothing like GitHub's check runs, so build status is only reported in the dashboard.

Building on submit

Perforce doesn't tell Unreal Cloud when someone submits, so your server does: a change-commit trigger runs a small script after each submit to a stream, and the script starts a build of a preset through Unreal Cloud's API. It runs after the submit completes, so it never blocks or slows one down.

#!/bin/sh
# Starts an Unreal Cloud build of a preset. Usage: unrealcloud-build.sh <preset-id>
API_KEY="uc_..."
STUDIO_ID="..."
PROJECT_ID="..."

curl -fsS --max-time 10 -X POST \
  -H "apiKey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"presetId\": \"$1\"}" \
  "https://api.unrealcloud.io/v1/studios/$STUDIO_ID/projects/$PROJECT_ID/builds" > /dev/null

chmod 700 unrealcloud-build.sh

unrealcloud change-commit //YourDepot/main/... "/path/to/unrealcloud-build.sh <preset-id>"

# Starts an Unreal Cloud build of a preset. Usage: unrealcloud-build.ps1 <preset-id>
param([Parameter(Mandatory)][string]$PresetId)
$ApiKey = "uc_..."
$StudioId = "..."
$ProjectId = "..."

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod -Method Post -TimeoutSec 10 `
  -Uri "https://api.unrealcloud.io/v1/studios/$StudioId/projects/$ProjectId/builds" `
  -Headers @{ apiKey = $ApiKey } `
  -ContentType "application/json" `
  -Body (@{ presetId = $PresetId } | ConvertTo-Json) | Out-Null

unrealcloud change-commit //YourDepot/main/... "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File C:\path\to\unrealcloud-build.ps1 <preset-id>"

Each submit starts one build, which syncs the stream's latest changelist, so submits close together can build the same changelist more than once.

Workspaces on your server

Builds sync through a workspace on your server, one per project and stream, named after them: the stream //YourDepot/main gives

uc-<project-id>-YourDepot-main

Every build of that stream reuses it. Builds don't record their files in it, so it doesn't grow your server's database, and builders only need read access.

Disconnecting

Disconnecting from project settings removes the password and fingerprint from Unreal Cloud. It doesn't touch your server, so the project's workspaces stay there. To remove them, list them, then delete each one:

p4 clients -e "uc-<project-id>-*"
p4 client -d uc-<project-id>-YourDepot-main

Your project ID is shown under the project's name.

Security

The password is stored encrypted and never leaves Unreal Cloud's servers. Builders get a login ticket instead, which expires after your server's ticket timeout (12 hours by default).

To invalidate the current ticket, log the service account out everywhere as a super user. The next build logs in again with the stored password:

p4 logout -a unrealcloud

To cut Unreal Cloud off entirely, change the service account's password or remove its line from p4 protect.