Lore Integration

Track revisions from Epic Games’ open-source, content-addressed version control system.

Table of contents

1. Overview
2. Configuration
   1. Connection Settings
   2. Credentials
3. Setup Steps
   1. 1. Add the Integration
   2. 2. Install the Lore CLI
   3. 3. Run the relay
4. Revision Delivery
   1. Option A: lore-bridge relay (recommended)
   2. Option B: Server-side hook (self-hosted loreserver)
5. Webhook Payload Contract
6. Features
   1. Revision Sync
   2. Asset Tracking
7. Troubleshooting
   1. Test Connection reports “Could not reach Lore server”
   2. No revisions appear
   3. Assets aren’t created
8. API Reference
   1. Webhook Endpoint
9. Best Practices

Overview

Lore is Epic Games’ next-generation, open-source (MIT) version control system, written in Rust and built for the large binary assets of game development. It is content-addressed (a Merkle tree over an immutable revision chain), chunks binary files for fragment-level deduplication, supports sparse/lazy workspaces, and is the built-in VCS for UEFN (Unreal Editor for Fortnite).

ButterStack integrates with Lore to:

• Record every revision pushed to the branches you watch (by content hash and monotonic revision number)
• Track changed assets through the shared asset pipeline (lineage, versions, approval requests)
• Surface revisions and assets alongside your builds and tasks
• Health-check your Lore server’s HTTP endpoint

Why a relay? Lore’s stock loreserver ships no built-in webhook — server hooks are compiled into the binary. ButterStack therefore receives revisions through the lightweight bin/lore-bridge relay, which you run near your Lore server.

Configuration

Connection Settings

ButterStack derives the health-check URL from the remote host using Lore’s HTTP port: http://<host>:41339/health_check.

Credentials

* Lore servers run unauthenticated when [server.auth] is omitted. Provide a token only if your server requires one. ButterStack’s /health_check probe never needs it.

Setup Steps

1. Add the Integration

1. Go to Project Settings → Integrations
2. Click Add Integration and select Lore
3. Enter your remote_url (and optionally repository, branch, auth token)
4. Click Test Connection (probes the server’s /health_check)
5. Save the integration

2. Install the Lore CLI

curl -fsSL https://raw.githubusercontent.com/EpicGames/lore/main/scripts/install.sh | bash

3. Run the relay

See Revision Delivery below.

Revision Delivery

Option A: lore-bridge relay (recommended)

Run the relay on a host that can reach your Lore server. It detects new revisions, fetches the changed-file list, and POSTs them to ButterStack:

bin/lore-bridge \
  --remote lore://lore.company.com:41337/your-repo \
  --webhook "https://your-butterstack.com/webhooks/lore?token=YOUR_WEBHOOK_TOKEN" \
  --branch main

Useful flags:

• --test — POST one synthetic revision and exit (no Lore server needed; great for verifying the webhook)
• --dry-run — print the JSON payload instead of POSTing
• --once — poll a single time and exit
• --interval <seconds> — poll cadence (default 15)

Under the hood the relay subscribes to / polls Lore for BranchPushed events and enriches each with lore revision info --delta. The Lore CLI does not emit JSON today, so parsing is best-effort; the robust long-term form is a gRPC client against Lore’s NotificationService + RevisionService.

Option B: Server-side hook (self-hosted loreserver)

If you build your own loreserver, compile in a BranchPush hook whose async post_handler POSTs to the webhook URL, then enable it in your server config:

[hooks.butterstack]
enabled = true
webhook_url = "https://your-butterstack.com/webhooks/lore?token=YOUR_WEBHOOK_TOKEN"

Webhook Payload Contract

The relay (or your hook) POSTs this JSON to /webhooks/lore?token={webhook_token}:

{
  "revision": "a1b2c3d4e5f6",
  "revision_number": 1052,
  "branch": "main",
  "repository": "your-repo",
  "user_id": "alice",
  "timestamp": "2026-06-17T14:21:00Z",
  "files": [
    { "path": "Content/Hero.uasset", "action": "Add", "size": 1048576, "is_file": true }
  ]
}

Only revision is strictly required. Files use Lore’s Add / Modify / Delete actions. Duplicate revisions within 30 seconds are de-duplicated.

Features

Revision Sync

When a revision is pushed:

1. ButterStack receives the relay’s webhook
2. Creates a Changelist record keyed by revision number (with the content hash, branch, and repository in metadata)
3. Runs the changed files through the shared asset analyzer — creating/updating assets, lineage, and versions
4. Raises approval requests for any approval tags found

Asset Tracking

Files with recognized asset extensions (.uasset, .fbx, .png, .wav, …) are tracked as assets, the same way Perforce changelists are — so asset lineage and approvals work identically regardless of which VCS you use.

Troubleshooting

Test Connection reports “Could not reach Lore server”

This is expected if your Lore server isn’t reachable from ButterStack (e.g. it’s on a private network). Revision delivery still works — the relay runs near your server and POSTs out to ButterStack. The connection test only probes the optional HTTP health endpoint.

No revisions appear

• Confirm the relay is running and pointed at the right branch (--branch)
• Verify the webhook token in the relay’s --webhook URL matches the integration
• Send a bin/lore-bridge --test revision to confirm the webhook path end-to-end
• Check Integration → Webhook events for received/failed events

Assets aren’t created

Only files with recognized asset extensions become assets. Code/text files are recorded on the revision but not tracked as assets.

API Reference

Webhook Endpoint

POST /webhooks/lore?token={webhook_token}
GET  /webhooks/lore/verify

See the payload contract above.

Best Practices

1. Run the relay close to your server — lower latency, and it works even when ButterStack can’t reach Lore directly.
2. Watch a specific branch — point the relay at your mainline to avoid noise from feature branches.
3. Use --test first — confirm the webhook works before wiring up the live stream.
4. Only add a token if your server requires one — most evaluation servers run unauthenticated.