Docs · App & code signing

CI & pipelines

Companies keep control of certificates and signing keys in Key Vault, while agencies and contractors build and release under the company’s policy. Sign Apple apps in GitHub Actions with short-lived CI devices and GitHub OIDC — no stored enrollment codes or signing secrets. Production API: https://api.liminalkeys.com. Private keys stay non-exportable in Key Vault; they never reach the runner. WatchTeams 2.1.0 (Devfinition) was signed through this CI path and shipped to the App Store (ephemeral CI device, no smart card on the runner). Customer story →

Preview: cross-platform 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

PathBest 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:

  1. 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.
  2. Allow it in a policy rule — Policy rules → Allow / sign → subject CI workload (trusted issuer) → your trust → Apply policy.
  3. Run your workflow — set LIMINAL_KEYS_TENANT_ID and LIMINAL_KEYS_CERT_SHA1 as 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).

Console CI and automation Trusts tab with setup checklist (mocked data)

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 with codesign -s.
  • Use --options runtime and --timestamp for 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.* }} inside run: 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

IssueCheck
OIDC / id-token errorspermissions: 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 deniedPolicy rule for CI workload (trusted issuer); click Apply policy
CI device capWait for TTL expiry or finish jobs so ci unenroll runs
sign-check failsRe-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)

GitLab, CircleCI, Bitrise, and AWS macOS capacity are not covered by copy-paste recipes yet. Google Cloud Build has no macOS workers. Use CI enrollment keys on a self-hosted Mac agent until a first-party wrapper ships.

Never commit enrollment codes, CI keys, OIDC tokens, or App Store Connect .p8 material.

Further reading

More essays and announcements: Articles on liminalkeys.com.

Related: Getting started · Liminal Keys for Mac · Console