Use Fastlane match for Ad Hoc Certificates and Profiles

Configure Fastlane match for Ad Hoc signing, refresh profiles for registered devices, and keep CI read-only without hiding certificate and private-key ownership.

Updated August 22, 2026

Fastlane match—an alias for sync_code_signing—can give developer and CI machines the same authorized signing identities and provisioning profiles. For Ad Hoc delivery, it solves synchronization—not device consent, Apple team ownership, Apple device limits, or artifact verification.

The current Fastlane action accepts type: "adhoc". Fastlane recommends read-only mode on CI so the build job installs existing assets without unexpectedly creating or changing certificates and profiles.

Establish signing ownership first

Before initializing match, identify the Apple Developer team, explicit app identifiers, certificate owner, storage administrator, and rotation procedure. Apple describes distribution certificates as sensitive team assets. Limit access to trusted organization members and do not move private keys through tickets, client forms, or ordinary email.

Fastlane supports encrypted signing-asset storage. Git storage uses a passphrase; the match documentation also describes Google Cloud and S3 storage modes. The stored material can include certificates, provisioning profiles, and private keys, so treat access to the storage plus its decryption secret as access to signing identities. Choose a backend whose access logs, recovery process, and least-privilege controls your team can operate.

match shares an identity that already belongs to one Apple Developer team. It does not make assets portable across teams: a profile, certificate, and App ID from Team A cannot authorize Team B’s bundle identifier. Pin the team in your Fastlane configuration whenever the operator can access more than one team.

Create or synchronize the Ad Hoc assets

Use an isolated signing repository or bucket, then initialize match for the intended team and app. A controlled operator lane can use either action name; this example uses the current canonical action name:

lane :sync_adhoc_signing do
  sync_code_signing(
    type: "adhoc",
    app_identifier: "com.example.clientapp",
    readonly: is_ci
  )
end

Run the write-capable setup from a controlled operator environment. CI should receive only the credentials necessary to read and decrypt the approved assets. An apparently valid profile from the wrong team is still wrong for the release. match can create or repair signing assets when it has authority, but it cannot reconstruct a missing private key that was never stored or imported into the signing system.

Refresh after registering new devices

Device registration and profile regeneration are separate. register_devices is additive: it registers new devices with Apple and does not remove devices omitted from its input. Fastlane documents combining it with:

sync_code_signing(
  type: "adhoc",
  app_identifier: "com.example.clientapp",
  force_for_new_devices: true
)

For Development and Ad Hoc profiles, force_for_new_devices checks whether the enabled device count changed and can regenerate the profile. It is a count-based trigger, not proof that a particular UDID is correct or that an older IPA has been refreshed. Fastlane notes that the option is ignored for App Store profiles because they do not contain device lists. force: true is a stronger option that regenerates profiles each time; use it only as a deliberate maintenance operation.

Do this in an authorized maintenance lane, not in every unreviewed pull request. A changed count is useful evidence, but it does not prove that the incoming identifier belongs to the intended client. Validate consent, device identity, team, and capacity before registration.

Keep CI read-only and explicit

A typical build lane synchronizes existing signing material before invoking build_app:

lane :client_adhoc do
  sync_code_signing(
    type: "adhoc",
    app_identifier: "com.example.clientapp",
    readonly: true
  )

  build_app(
    scheme: "ClientApp",
    export_method: "ad-hoc"
  )
end

Treat the storage credential and decryption passphrase as CI secrets. Do not print them, write them into artifacts, or expose them to tester-facing systems. Rotate access when a team member leaves, and test recovery before the only working signing machine is lost. Read-only mode prevents CI from generating or changing Apple assets; it does not remove the need to protect the downloaded private key during the job.

Diagnose the common failure boundaries

Certificate exists, private key missing: the machine cannot form a signing identity. Confirm the key pair in Keychain or match storage.
Profile is stale: register the device, regenerate the correct Ad Hoc profile, resync, and rebuild.
Wrong app identifier or team: pin both values and inspect the downloaded profile.
CI tries to create assets: restore readonly: true and run changes through the controlled maintenance lane.
Build succeeds but client install fails: inspect the exported IPA. A synchronized local profile does not prove the artifact embedded it.

Continue with building an Ad Hoc IPA using Fastlane, then inspect the final signature and embedded profile. IPAFlow is in Private Beta / In Development and can receive a verified artifact for an authorized client-delivery workflow; it does not replace match storage or take ownership of your Apple signing secrets.

Related next steps

Next step. Validate the signing prerequisites and final IPA before feeding the artifact into a client delivery workflow. Join Early Access.