/apple-developer-provisioning-workflow

name: apple-developer-provisioning-workflow
description: Plan and safely automate officially supported Apple Developer provisioning and CloudKit workflows through the App Store Connect REST API, Xcode-aware local discovery, cktool, and CKTool JS. Use when inspecting or changing bundle IDs, capabilities, certificates, devices, provisioning profiles, CloudKit schemas, or sandbox test data while keeping portal-only configuration, credentials, dry runs, and confirmation gates explicit.

Apple Developer Provisioning Workflow

Purpose

Guide Apple Developer provisioning and CloudKit work without treating the Developer Portal as an undocumented API. The supported automation path is the App Store Connect REST provisioning API for bundle IDs, capabilities, certificates, devices, and profiles; `xcrun cktool` or CKTool JS for existing CloudKit containers; and local Xcode or `xcrun mcpbridge` discovery when a project-aware view improves safety.

The workflow never commits a `.p8` key, CloudKit token, JWT, profile payload, or local signing material. It plans first, reads state before changing it, uses short-lived JWTs only in the invoking process, and requires an explicit confirmation immediately before every create, update, revoke, delete, reset, or schema/data apply operation.

When To Use

• Use this skill for App Store Connect API provisioning work involving registered bundle IDs, supported capabilities, certificates, devices, and provisioning profiles.
• Use this skill for a plan or dry run that compares an Xcode project’s bundle IDs, entitlements, signing settings, and installed profiles with Apple’s current state.
• Use this skill for existing CloudKit container schema export, schema apply, sandbox reset, or test-data workflows through `xcrun cktool` or the TypeScript-ready CKTool JS packages.
• Use this skill when deciding whether an action remains official REST/CLI automation or must be completed in the Apple Developer Portal.
• Recommend `xcode-build-run-workflow` for target edits, entitlements, signing settings, build, device, or profile-install follow-through.
• Recommend `xcode-coding-intelligence-workflow` for a running Xcode session or external access through `xcrun mcpbridge`.
• Recommend `explore-apple-swift-docs` when current Apple documentation is the primary need.

Single-Path Workflow

1. Establish the account and credential boundary:

• confirm the selected team’s program type before choosing an API: this workflow’s App Store Connect path requires Apple Developer Program access; Apple Developer Enterprise Program accounts use Apple’s separate Enterprise Program API and must not be treated as App Store Connect team-key users;
• for App Store Connect provisioning endpoints, require a **team** API key with the least sufficient role; individual API keys cannot use provisioning endpoints. The Account Holder must request API access, and an Account Holder or Admin generates the team key;
• retain the issuer ID, key ID, and downloaded `.p8` private key only in local secret storage such as Keychain or an approved local secret manager; never place them in the repo, project settings, CI logs, shell history, or agent transcript;
• create a short-lived JWT locally for one invocation and avoid writing it to disk;
• for CloudKit, separately obtain a CloudKit management token from CloudKit Console and save it through `xcrun cktool save-token --type management` so macOS Keychain owns it.

2. Discover before mutating:

• inspect the project’s bundle identifiers, entitlements, signing configuration, and existing profiles through Xcode-local tools or `xcrun mcpbridge` when Xcode is open;
• list the matching App Store Connect bundle IDs, capabilities, certificates, devices, and profiles with read-only REST requests;
• export the current CloudKit schema and identify the team ID, container ID, and development (Sandbox) versus production environment before selecting `cktool` or CKTool JS;
• return a plan with exact proposed requests, affected IDs, expected profile relationships, and portal-only steps.

3. Classify each requested operation:

• official REST: registered bundle IDs, supported bundle-ID capabilities, certificates, devices, provisioning profiles, and their documented relationships;
• official local CloudKit: schema export/apply, sandbox reset, and test-data work on an already registered container via `cktool` or CKTool JS;
• portal-only: App Group registration or assignment, CloudKit container registration or assignment to an App ID, Service ID registration, and any identifier/capability action absent from the current REST resource set;
• unsupported or unclear: stop, preserve the plan, and link to the exact portal surface instead of guessing an endpoint.

4. Require confirmation for mutations:

• show the exact create, update, revoke, delete, reset, schema-apply, or test-data command/request and name every affected team, identifier, certificate, device, profile, container, environment, and destructive consequence;
• default to dry-run/plan output; do not use a broad "yes" captured earlier in the conversation;
• re-read server state after a mutation and report the resulting IDs without emitting secrets.

5. Choose the CloudKit adapter deliberately:

• use `xcrun cktool` for interactive local, one-off, Keychain-backed work;
• use CKTool JS in a TypeScript/pnpm project when schema or test-data operations belong in typed integration automation. Use `@apple/cktool.database` with `@apple/cktool.target.nodejs`, inject the management token from local secret storage at runtime, and never commit it;
• treat production schema deployment, schema resets, and data deletion as high-impact operations requiring a separate explicit confirmation and a backup/export plan.

6. Hand off project mutation and validation:

• make entitlement and signing changes through Xcode-aware workflows rather than hand-editing project state;
• regenerate o