t1k:playablelabs:ci:arc-workflow
| Field | Value |
|---|---|
| Module | ci |
| Version | 1.17.3 |
| Effort | medium |
| Tools | — |
Keywords: arc pack and smoke, packer deploy key, PLAYABLE_ENGINE_DEPLOY_KEY, playable.yml workflow
How to invoke
Section titled “How to invoke”/t1k:playablelabs:ci:arc-workflow<game repo> [--engine-host none|web]ARC pack + smoke workflow (web / none playables)
Section titled “ARC pack + smoke workflow (web / none playables)”Scope: a game repo that builds with bun run build into dist/ (engine host none or web) gets a
GitHub Actions job that packs it with the PlayableLabs packer and smokes every network on a Linux ARC
pod. Cocos games cannot use this: Creator builds need the Windows cocos Jenkins agent, see
t1k-playablelabs-ci-jenkins (and core t1k-jenkins-cocos to run a job). Authoring Cocos game code
is the Cocos kit’s job. Generic CI authoring: core t1k-devops-engineer.
- Confirm the game builds: root
package.jsonwith abuildscript that writesdist/index.html(contract:PlaybleEngine:.claude/skills/playable-engine/references/jenkinsfile.mdsection 6). - Copy the template to
.github/workflows/playable.yml. Source of truth is PlaybleEngine’sci/templates/web-game/playable.yml+README.md;references/playable.yml.tmpl.mdmirrors it. Edit only the settings its header lists:branches:,ENGINE_HOST(webornone), Node version,PLA_PACK_FLAGS. Keep the triggers free of apaths:filter: a required check that apaths:filter skips never reports and blocks the merge forever (skip inside the job with a stepif:instead). - Make sure the secret exists (next section). Without it the job fails fast with
::error::Secret PLAYABLE_ENGINE_DEPLOY_KEY is not set. - Open a PR. Expected: a
testjob, thenpack-smoke(timeout-minutes: 30; first-run timings inreferences/origin-notes.md), a size table in the run summary, artifactdist(14 days) and artifactplayablesholdingpack-report.json,smoke-report.json,applovin/index.htmland each zip. Maketestandpack-smokerequired checks only after that first green run. - Optional Discord post (the template’s last step, “Notify Discord (optional)”): enabled only by the secret
DISCORD_BOT_TOKEN, which is not provisioned in the org today. Until it is, the JenkinsPlayablePackerrun is the path that posts (t1k-playablelabs-ci-jenkins; setPARAM_AGENT_LABEL=web-linuxto run a web/none build on the Linux agents). Optional variables:PLAYABLE_DISCORD_THREAD_ID(thread override),PLAYABLE_PUBLISH_BASE_URLandPLAYABLE_ZIP_NAME(Quick Play and ZIP links). Detail: the engine README section “Discord notification”.
Pipeline shape (engine template, from TimelineUp playable.yml)
Section titled “Pipeline shape (engine template, from TimelineUp playable.yml)”| Piece | Value |
|---|---|
| Runners | [self-hosted, arc, the1studio, org] (Linux pods) |
| Jobs | test (20 min: build, bun run test --if-present) uploads dist; pack-smoke (30 min) needs: test, downloads it. pack-smoke has NO game checkout |
| Packer checkout | actions/checkout@v4 of The1Studio/PlaybleEngine over SSH, ssh-key: secrets.PLAYABLE_ENGINE_DEPLOY_KEY, ref: env.PLAYABLE_ENGINE_REF (master default; engine_ref input per manual run) |
| Packer build | bun install --frozen-lockfile && bun run build in the checkout; browser via bunx playwright install --with-deps chromium |
| Pack | bun PlaybleEngine/dist/cli.js --build dist --out pack --engine-host "$ENGINE_HOST" --network "$PLA_NETWORKS" $PLA_PACK_FLAGS --json > pack/pack-report.json (PLA_PACK_FLAGS = --deflate --webp; PLA_NETWORKS defaults to all; --engine-host goes to BOTH pack and smoke, see t1k-playablelabs-base-engine-hosts) |
| Smoke | bun scripts/smoke.cjs --out pack --report pack/pack-report.json --engine-host <h> --networks all --out-report pack/smoke-report.json |
| Concurrency | group per workflow+ref, cancel-in-progress: true |
Pack exit codes: 0 within budget, 1 over budget, 2 usage error (PlaybleEngine:src/cli.ts exit-code
comment; Jenkinsfile/PlayablePacker Pack stage). A red pack or smoke step fails the job; fix the
cause, never re-run hoping it flips.
Deploy key: one-click handoff (credential step, needs the user)
Section titled “Deploy key: one-click handoff (credential step, needs the user)”Convention (engine README): one read-only deploy key PER game repo on PlaybleEngine, titled
<Repo> CI (read-only), so one game’s key can be revoked without breaking the others; its private half
goes in that repo’s secret PLAYABLE_ENGINE_DEPLOY_KEY. The engine README carries the copy-pasteable
commands with REPO=<name>; the block below is the same shape. Prefer a per-repo key over reusing one.
Creating or attaching a key is a credential action: get the user’s go-ahead first. Check first:
gh repo deploy-key list --repo The1Studio/PlaybleEngine for <Repo> CI (read-only). Otherwise run, as the user:
REPO=<game-repo> # name only, no org prefixT=$(mktemp -d) && ssh-keygen -t ed25519 -N "" -C "$REPO CI (read-only)" -f "$T/key" -qgh repo deploy-key add "$T/key.pub" --repo The1Studio/PlaybleEngine --title "$REPO CI (read-only)"gh secret set PLAYABLE_ENGINE_DEPLOY_KEY --repo "The1Studio/$REPO" < "$T/key"rm -rf "$T"gh repo deploy-key add is read-only unless --allow-write is passed: never pass it. Never cat,
echo or log $T/key. Confirm after: gh secret list --repo The1Studio/<game-repo> shows the name,
gh repo deploy-key list --repo The1Studio/PlaybleEngine shows the key with read-only. Verified-populated
fields: none can be prefilled; the commands carry every value. The game repo must also be allowed to use the
org’s ARC runner group arcpods (org settings, Actions, Runner groups).
Hard rules
Section titled “Hard rules”- The pod may lack
ssh: the template guards withcommand -v ssh || apt-get install openssh-client(slingnshot comment citingci-cd-trigger-design.md#11; that doc is not in the packer clone: unverified). - cwebp: the general
--webprules are int1k-playablelabs-base-pack. Pod-specific: PlaybleEngine’s own CI saw 1.5.0 preinstalled and 1.2.2 from apt; its byte-compared jobs install a pinned libwebp 1.5.0 from Google’s release, sha256-checked (PlaybleEngine:.github/workflows/ci.yml). The size-only template tolerates any version. - No GitHub cache on ARC: no
cache:on setup-bun, no actions/cache (no zstd in the pod image;ci.ymlheader). Expect coldbun install --frozen-lockfile. - Some pods already carry a Playwright Chromium and
playwright installcan refuse an old distro: packerci.ymlguard-installs only whenchromium-*is missing and falls back to the browser-only install. The template uses the unconditional install as slingnshot does; if it fails on a pod, use the guard fromci.yml. - Bun 1.4.3, not the bare
enginesfloor: set what the game’s RESOLVED toolchain needs (engine README “Why Node 22” explains vite/vitest floors; Bun 1.4.3 runs them). A pod without Bun is unverified:setup-bunis used everywhere.
Verified against
Section titled “Verified against”PlaybleEngine@d76f263 (2026-10-07): ci/templates/web-game/{playable.yml,README.md} (the mirror is
byte-identical to playable.yml), .github/workflows/ci.yml, src/cli.ts USAGE (unchanged since 4ee4272),
.claude/skills/playable-engine/references/jenkinsfile.md; TimelineUpThreePLA@464ddbd
.github/workflows/playable.yml; gh repo deploy-key add --help, gh secret set --help. Not verified: a
live run of the Discord step (the engine README says the same).
Hard rules
Section titled “Hard rules”- The workflow checks out the packer at a moving ref (
master);masteris unprotected and is also what Jenkins deploys, so a packer merge can change your CI result. Pin a SHA when you need stability. - A green smoke is not a size gate: pack exits 1 on budget breach. On the pack path every row is
passorfail(checkBudget(..., false),src/cli.ts,src/core/measure.ts);unknownis not produced there, so a source comment saying networks with no ceiling exit 0 asunknownis stale. Reademitted[].verdict.status+emitted[].sizeVerifiedper row; exit 0 only means no row failed (sizeVerified: false= no vendor ceiling read). Same wording ast1k-playablelabs-base-pack. - Missing secret on a fork PR: secrets are not exposed to forks, so
pack-smokefails there by design. - A job that calls a game
bun runscript must check the game repo out first. The template’spack-smokeneeds only thedistartifact, so it has no game checkout. If you change the Pack step tobun run pack, addactions/checkoutBEFORE thedistdownload (checkout cleans the workspace); otherwisebunfails withENOENT ... package.json(references/origin-notes.md). - Flag rules live with the flag, not here:
--engine-hoston pack and smoke and the web-host contract (t1k-playablelabs-base-engine-hosts),--webp/cwebp(t1k-playablelabs-base-pack),--canaryis Cocos-only (t1k-playablelabs-base-smoke): do not add it to the web workflow. - No
paths:filter onpull_request/push(see step 2). A game with required checks that adds one blocks every PR it skips.