Setup & usage guide

Everything from zero to locking your first asset: create an org, connect a bucket you own, make a repo, install the Unreal plugin, and check out files like Perforce — on top of plain git.

How it works

Lockstep keeps your code and small files in git and streams big binary assets straight into a bucket you own (Cloudflare R2, Backblaze B2, Wasabi, MinIO, or S3) via the Git LFS protocol. The coordination server only ever brokers short-lived presigned URLs — blob bytes never pass through it. On top, it adds the thing git can't do for binaries: Perforce-grade file locking, enforced in-editor by the Unreal plugin.

Control plane (dashboard, you sign in with OAuth): create an org, connect storage once, create repos, invite members, mint tokens.
Data plane (git, git-lfs, the UE plugin): authenticate with a token and receive only presigned URLs — never your bucket keys.

1. Account & org

Sign in

Go to app.lockstepcloud.com and sign in with GitHub or Google. No password to manage.

Create an org

An org is where your team, repos, storage and billing live. Pick a name; the URL slug is permanent. Each active member is a billable seat (roles: owner / admin / member).

2. Connect storage

In the dashboard, open Storage and connect your bucket once at the org level. You supply S3-compatible credentials (endpoint, region, bucket, access key, secret); Lockstep test-connects and stores the secret encrypted at rest (AES-256-GCM). Clients never see these keys — they only get presigned URLs.

Bring your own bucket

R2 and B2 are cheapest because egress is free via the Bandwidth Alliance. You keep ownership and control retention/GC.

3. Create a repo

Open Repositories → Create and give it a name. The slug becomes your repo URL:

https://api.lockstepcloud.com/<your-repo-slug>

On the repo page you'll find the Use Lockstep for assets card with a ready-to-commit .lfsconfig, an install snippet, and a Download Unreal plugin button. The Lock overview on the same page shows every active lock.

4. Prepare your UE project

Your Unreal project must be a git working copy. Two files go at its root and get committed:

`.lfsconfig` — point LFS at your repo

[lfs]
  url = https://api.lockstepcloud.com/your-repo-slug

`.gitattributes` — mark binary types `lockable`

Locking only applies to file types flagged lockable (unmergeable binaries). Mergeable text/code stays normal git.

*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap   filter=lfs diff=lfs merge=lfs -text lockable
*.fbx    filter=lfs diff=lfs merge=lfs -text lockable
*.blend  filter=lfs diff=lfs merge=lfs -text lockable
# textures/audio: LFS but not lockable (safe to fetch concurrently)
*.png filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text

git lfs install
git add .gitattributes .lfsconfig
git commit -m "Use Lockstep for LFS + lock binary assets"

Prerequisites

Install git and git-lfs and make sure they're on your PATH.

5. Install the Unreal plugin

Download the plugin (see Downloads) and unzip it into your project so you get <YourProject>/Plugins/LockstepSourceControl/.
Open the project. On Windows the binaries are prebuilt; on macOS/Linux the editor compiles the source on first open (click Yes to rebuild).
Edit → Plugins, search Lockstep (category: Source Control), make sure it's enabled, restart if asked.

6. Connect & sign in

Pick the provider

Revision Control (bottom-right status bar) → Connect → Provider: Lockstep.

Server URL

Paste your repo URL — the same value as lfs.url in .lfsconfig, e.g. https://api.lockstepcloud.com/your-repo-slug.

Sign in to Lockstep

Click Sign in to Lockstep. Your browser opens; authorize with GitHub/Google and you're returned automatically. The access token is stored securely in your OS credential manager — no env vars, no copy-paste.

Accept & connect

Accept Settings → Connect. The status bar shows Lockstep connected.

7. Daily workflow

The core loop for a binary asset is Check Out → edit → Submit:

Action	How	What happens
Check out	Right-click asset → Revision Control → Check Out	Acquires your exclusive lock. Others can't edit it until you release.
See who holds a lock	Asset icon / tooltip in the Content Browser	"Checked out by name" badge when someone else holds it.
Submit	Toolbar → Submit Content	`git add` + `commit` + `push`, then releases your lock.
Add a new asset	Save it, then Submit	Marked for add and committed.
Get latest	Revision Control → Sync	`git pull`; LFS blobs stream from your bucket.
Discard + release	Revision Control → Revert	Throws away local changes and releases your lock.

Verify a checkout round-trips by opening your repo in the dashboard — the Active locks list should show it.

8. Locking explained

Binary Unreal assets can't be merged, so "resolve later" means someone's work is destroyed. Lockstep is therefore hybrid:

File type	Model
Source / code (`.cpp .h .ini .json`)	git optimistic merge — no locks
Binary assets (`.uasset .umap .fbx .blend`)	Pessimistic lock — one editor at a time, enforced in-editor

Acquisition is a single transactional insert keyed UNIQUE(repo, path), so there's no double-lock race.

Tokens & CI

The in-editor sign-in is the easy path for people. For CI, scripts, or headless builds, mint a Personal Access Token in the dashboard (Access tokens → Generate; scopes lock/read/write) and provide it as the LOCKSTEP_TOKEN environment variable, or as the password for git over HTTPS. The token is shown once. Tokens are revocable from the same page.

Admin & force-unlock

Owners and admins can force-release a lock held by someone else (e.g. a teammate is offline) — a plain member cannot steal a lock. Storage configuration is owner/admin-only. Stale locks are managed with TTL/heartbeat.

Downloads

Unreal Engine 5.7. All assets live on the release page:

Windows (prebuilt) Drop into Plugins/ and go — no compiler needed. macOS / Linux (source) The editor compiles it on first open (needs Xcode / clang).

All downloads & release notes →

Troubleshooting

Symptom	Fix
Revision Control actions all greyed out	The provider isn't connected, or the project isn't a git repo. Check the project has `.git` and is connected (Output Log, filter `Lockstep`).
"Check Out" disabled on an asset	The type isn't marked `lockable` in `.gitattributes`, or status is stale — add the flag, then Revision Control → Refresh.
"Cannot check out: Lockstep is not configured"	You're not signed in. Open the provider settings and click Sign in to Lockstep (or set `LOCKSTEP_TOKEN`).
"Already locked by …"	Someone else holds the lock. Coordinate, or an admin can force-release it.

All links

Dashboard — sign in, orgs, storage, repos, tokens, locks.
Plugin downloads — Windows & macOS/Linux.
Source on GitHub — fair-source (BSL 1.1).
Architecture — the full design.
[email protected] — support.