Skip to content

t1k:playablelabs:ci:arc-workflow

FieldValue
Moduleci
Version1.17.3
Effortmedium
Tools—

Keywords: arc pack and smoke, packer deploy key, PLAYABLE_ENGINE_DEPLOY_KEY, playable.yml workflow

/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.

  1. Confirm the game builds: root package.json with a build script that writes dist/index.html (contract: PlaybleEngine:.claude/skills/playable-engine/references/jenkinsfile.md section 6).
  2. Copy the template to .github/workflows/playable.yml. Source of truth is PlaybleEngine’s ci/templates/web-game/playable.yml + README.md; references/playable.yml.tmpl.md mirrors it. Edit only the settings its header lists: branches:, ENGINE_HOST (web or none), Node version, PLA_PACK_FLAGS. Keep the triggers free of a paths: filter: a required check that a paths: filter skips never reports and blocks the merge forever (skip inside the job with a step if: instead).
  3. Make sure the secret exists (next section). Without it the job fails fast with ::error::Secret PLAYABLE_ENGINE_DEPLOY_KEY is not set.
  4. Open a PR. Expected: a test job, then pack-smoke (timeout-minutes: 30; first-run timings in references/origin-notes.md), a size table in the run summary, artifact dist (14 days) and artifact playables holding pack-report.json, smoke-report.json, applovin/index.html and each zip. Make test and pack-smoke required checks only after that first green run.
  5. 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 Jenkins PlayablePacker run is the path that posts (t1k-playablelabs-ci-jenkins; set PARAM_AGENT_LABEL=web-linux to run a web/none build on the Linux agents). Optional variables: PLAYABLE_DISCORD_THREAD_ID (thread override), PLAYABLE_PUBLISH_BASE_URL and PLAYABLE_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)”
PieceValue
Runners[self-hosted, arc, the1studio, org] (Linux pods)
Jobstest (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 checkoutactions/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 buildbun install --frozen-lockfile && bun run build in the checkout; browser via bunx playwright install --with-deps chromium
Packbun 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)
Smokebun scripts/smoke.cjs --out pack --report pack/pack-report.json --engine-host <h> --networks all --out-report pack/smoke-report.json
Concurrencygroup 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:

Terminal window
REPO=<game-repo> # name only, no org prefix
T=$(mktemp -d) && ssh-keygen -t ed25519 -N "" -C "$REPO CI (read-only)" -f "$T/key" -q
gh 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).

  • The pod may lack ssh: the template guards with command -v ssh || apt-get install openssh-client (slingnshot comment citing ci-cd-trigger-design.md #11; that doc is not in the packer clone: unverified).
  • cwebp: the general --webp rules are in t1k-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.yml header). Expect cold bun install --frozen-lockfile.
  • Some pods already carry a Playwright Chromium and playwright install can refuse an old distro: packer ci.yml guard-installs only when chromium-* 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 from ci.yml.
  • Bun 1.4.3, not the bare engines floor: 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-bun is used everywhere.

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).

  • The workflow checks out the packer at a moving ref (master); master is 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 pass or fail (checkBudget(..., false), src/cli.ts, src/core/measure.ts); unknown is not produced there, so a source comment saying networks with no ceiling exit 0 as unknown is stale. Read emitted[].verdict.status + emitted[].sizeVerified per row; exit 0 only means no row failed (sizeVerified: false = no vendor ceiling read). Same wording as t1k-playablelabs-base-pack.
  • Missing secret on a fork PR: secrets are not exposed to forks, so pack-smoke fails there by design.
  • A job that calls a game bun run script must check the game repo out first. The template’s pack-smoke needs only the dist artifact, so it has no game checkout. If you change the Pack step to bun run pack, add actions/checkout BEFORE the dist download (checkout cleans the workspace); otherwise bun fails with ENOENT ... package.json (references/origin-notes.md).
  • Flag rules live with the flag, not here: --engine-host on pack and smoke and the web-host contract (t1k-playablelabs-base-engine-hosts), --webp/cwebp (t1k-playablelabs-base-pack), --canary is Cocos-only (t1k-playablelabs-base-smoke): do not add it to the web workflow.
  • No paths: filter on pull_request/push (see step 2). A game with required checks that adds one blocks every PR it skips.