Docs · App & code signing
CI & pipelines
liminal-keys 0.1.x installs from the public API or setup-liminal-keys — see Cross-platform CLI. Linux and Windows digest signing: Preview. Supported today: self-hosted macOS with the Liminal Keys Mac app. GitHub-hosted macOS: being verified.
Choose a path
| Path | Best for |
|---|---|
| GitHub Actions + OIDC (below) | Self-hosted macOS runners with the Liminal Keys Mac app; sign@v1 enroll + export@v1 for App Store IPA (no private repo checkout) |
| GitHub-hosted macOS (being verified) | Ephemeral macos-* runners — use install-host on sign@v1 (see below); not supported for production use until verified |
| CI enrollment key | Runners without OIDC — scoped lkci_ secret (lower assurance than OIDC) |
| Persistent self-hosted Mac | Long-lived build Mac with interactive enroll and LiminalKeysHostCLI enroll — see Self-hosted Mac |
Console setup
Step-by-step guides: CI quickstart · CI reference · Cross-platform CLI (preview) (full markdown also in the llms-full.txt or the public docs pages below).
In Liminal Console open CI & automation — tabs Trusts, Activity, and Enrollment keys.
The Set up CI signing checklist on Trusts tracks three steps:
- Add a GitHub trust — pin one repository (for example
acme-corp/acme-ios) with required branch or tag, workflow file, and at least one identity in scope. Incomplete trusts return 400; duplicate trust names return 409. - Allow it in a policy rule — Policy rules → Allow / sign → subject CI workload (trusted issuer) → your trust → Apply policy.
- Run your workflow — set
LIMINAL_KEYS_TENANT_IDandLIMINAL_KEYS_CERT_SHA1as repository variables, then run the sample dry-run workflow.
Refused enrollments appear under Activity — open the refusal drawer for reason codes and Expected vs Got. Use Create trust from this run or Paste claims from a test run on Add trust to prefill fields from verified run data (OIDC JWT is verified once and not stored).
GitHub Actions (self-hosted macOS runners)
Copy workflow YAML from the public sample repo
Quickstart (zero → signed build)
— dry-run template, sign-sample.yml, app-store-release.template.yml, Developer ID notarization template, and troubleshooting.
Do not maintain a second copy in your docs; fork the sample patterns instead.
Every OIDC job needs permissions: id-token: write and contents: read.
Token audience: https://api.liminalkeys.com/t/<tenant-guid> (lowercase tenant UUID from Console).
Action input ttl-minutes maps to Host CLI --ttl (for example 60m).
On self-hosted macOS runners (supported today), run LiminalKeys/liminal-keys-ci-sample/sign@v1
with the Liminal Keys Mac app available on the runner. The step enrolls a short-lived CI device,
runs a sign readiness check, and always attempts unenroll in a post step.
Outputs include signing-sha1, device-id, and expires-at (also
LIMINAL_KEYS_SIGNING_SHA1 in job env).
GitHub-hosted macOS runners (being verified). On ephemeral GitHub-hosted macos-* runners,
set the Action input install-host so sign@v1 installs Liminal Keys for Mac on the runner before enroll.
This path is being verified — do not treat GitHub-hosted runners as supported for production until we publish verification.
Signing tips
- Sign nested frameworks and helpers first, then the app — do not use
codesign --deep. - Virtual identities may not appear in
security find-identity; use the Console SHA-1 withcodesign -s. - Use
--options runtimeand--timestampfor distribution builds. For example, WatchTeams 2.1.0 (Devfinition) was signed through this CI path and shipped to the App Store. - Pass secrets only via
env:in shell steps — never expand${{ secrets.* }}insiderun:script text.
macOS app notarization (your credentials)
macOS app notarization (DMG, pkg, or notarized Mac app bundles) runs after Liminal Keys signing and does not need an active CI device.
Store your App Store Connect API key in your GitHub secrets (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8 or ASC_KEY_P8_BASE64).
Apple lets you download the .p8 only once at key creation — save it in secrets immediately.
Liminal Keys never sees or stores your App Store Connect private key.
Sign the payload, submit with xcrun notarytool, then xcrun stapler staple.
See Apple’s
notarization documentation.
This section applies only to optional macOS app notarization steps (not iOS App Store releases such as WatchTeams 2.1.0).
CI enrollment keys (no OIDC)
On CI & automation, create a CI enrollment key, copy the one-time lkci_… secret into
LIMINAL_KEYS_CI_KEY (GitHub secret / env only), and point the sign Action at your tenant and SHA-1.
Prefer GitHub OIDC when available — OIDC uses per-job tokens with replay protection; shared CI keys are easier to misuse if leaked.
- uses: LiminalKeys/liminal-keys-ci-sample/sign@v1
env:
LIMINAL_KEYS_CI_KEY: ${{ secrets.LIMINAL_KEYS_CI_KEY }}
with:
tenant-id: ${{ vars.LIMINAL_KEYS_TENANT_ID }}
identity-sha1: ${{ vars.LIMINAL_KEYS_CERT_SHA1 }}
Security & limits
- Each job gets a short-lived CI device enrolled with GitHub OIDC or a CI key.
- Signing calls the cloud API; private keys remain in Key Vault custody.
- Default CI device lifetime: 60 minutes (request 5–120 with
ttl-minutes/--ttl). - Concurrent CI devices: 2 during beta, 5 on paid plans (trust-level caps may lower this).
- Audit: Sign audit lists each signing operation; match CI device id from Action output
device-id. CI & automation → Activity lists enrollments and refusals with run links when available.
Troubleshooting
| Issue | Check |
|---|---|
| OIDC / id-token errors | permissions: id-token: write; fork PRs often cannot mint tokens |
| Enrollment refused / 403 The identity token was refused. | Activity refusal drawer — branch, workflow file, repository, or environment mismatch; edit trust or run from allowed branch/workflow |
| Sign denied | Policy rule for CI workload (trusted issuer); click Apply policy |
| CI device cap | Wait for TTL expiry or finish jobs so ci unenroll runs |
| sign-check fails | Re-run; identity SHA-1 in trust scope; smartcard token enabled on runner |
Self-hosted Mac (persistent runner)
Install Liminal Keys for Mac on a dedicated build Mac, enroll once with an enrollment code from
Console → Devices, then use LiminalKeysHostCLI enroll, refresh, and status
with LIMINAL_KEYS_API_BASE_URL=https://api.liminalkeys.com.
Policy subjects use an enrolled device, not CI workload types.
This path is separate from short-lived CI devices on GitHub Actions — do not store enrollment codes in workflow secrets for CI signing.
Other platforms (coming later)
.p8 material.
Further reading
- When CI ships your iPhone app, who holds the signing key? (Medium, Liminal Keys)
- Your release pipeline signs your app. Does it need to hold the key? (LinkedIn, Devfinition)
More essays and announcements: Articles on liminalkeys.com.
Related: Getting started · Liminal Keys for Mac · Console