fastlane-plugin-voip_push_certificate

Create and renew Apple VoIP Services push certificates (the certificate type PushKit requires) from a fastlane lane.

fastlane's built-in get_push_certificate (pem) handles development, production and website push certificates, but not VoIP ones. This plugin fills that gap using the same Spaceship APIs, so it behaves the way you already expect pem to behave.

Getting Started

Requires Ruby 3.1 or newer.

Add the plugin to your project:

fastlane add_plugin voip_push_certificate

Or, to use it straight from source without installing the gem, add this to your fastlane/Pluginfile:

gem 'fastlane-plugin-voip_push_certificate', git: 'https://github.com/Rafinha-rf/fastlane-plugin-voip_push_certificate'

Usage

lane :renew_voip do
  get_voip_push_certificate(
    app_identifier: "com.example.app",
    output_path: "./certs"
  )
end

By default this creates voip_com.example.app.pem and voip_com.example.app.p12 (plus the private key) in output_path, but only if the current certificate expires within 30 days. Otherwise it logs how long the existing one is still valid and does nothing.

The action returns the path to the generated .pem, or nil when the existing certificate was kept. All generated paths are also exposed through the lane context:

lane_context[SharedValues::VOIP_PUSH_CERTIFICATE_PEM_PATH]
lane_context[SharedValues::VOIP_PUSH_CERTIFICATE_P12_PATH]
lane_context[SharedValues::VOIP_PUSH_CERTIFICATE_PKEY_PATH]
lane_context[SharedValues::VOIP_PUSH_CERTIFICATE_CER_PATH]

Options

Option	Type	Default	Description
app_identifier	String	from Appfile	The bundle identifier of your app
username	String	from Appfile	Your Apple ID username
team_id	String	from Appfile	Developer Portal team ID, if you're in multiple teams
team_name	String	from Appfile	Developer Portal team name, if you're in multiple teams
active_days_limit	Integer	30	Renew only if the current certificate expires within this many days
force	Boolean	false	Create a new certificate even if the current one is still valid
revoke_existing	Boolean	false	Revoke the matching certificate before creating a new one. See the warning below
generate_p12	Boolean	true	Also write a .p12 file
p12_password	String	none	Password for the .p12 file
save_private_key	Boolean	true	Also write the private key as a .pkey file
save_cer	Boolean	false	Also write the raw DER certificate as a .cer file
bag_attributes	Boolean	false	Write the .pem with OpenSSL bag attributes. See below
pem_name	String	voip_<app_identifier>	Base file name for the generated files
output_path	String	.	Directory to write the certificates into

Every option also has an environment variable, e.g. VOIP_PUSH_CERTIFICATE_APP_IDENTIFIER.

Things worth knowing

There is no development/production distinction

Apple issues a single VoIP Services certificate that is valid for both the sandbox and the production APNs environments. That is why, unlike get_push_certificate, this action has no development option.

Revoking is opt-in, on purpose

Apple allows at most two active VoIP certificates per App ID. When that limit is reached the action fails with an explanation rather than revoking anything, because revoking a certificate immediately stops every push provider still using it, including your production one.

Set revoke_existing: true only when you are sure nothing depends on the old certificate:

get_voip_push_certificate(
  app_identifier: "com.example.app",
  force: true,
  revoke_existing: true
)

The bag_attributes option

Some push providers reject a plain concatenated PEM and expect the format that openssl pkcs12 -nodes produces, with friendlyName and localKeyID headers around each block. If yours does, set bag_attributes: true. The default (false) matches what get_push_certificate writes: the certificate followed by the private key, nothing else.

Authentication

This uses Spaceship's Apple Developer Portal API, which needs an Apple ID and password:

export FASTLANE_USER="you@example.com"
export FASTLANE_PASSWORD="…"

Two-factor authentication is supported through fastlane's usual session mechanism (FASTLANE_SESSION, fastlane spaceauth).

App Store Connect API keys are not supported. Apple's App Store Connect API does not cover push certificates, so the portal API is the only option. This is a limitation of Apple's API, not of this plugin. get_push_certificate has exactly the same constraint.

Running tests

bundle install
bundle exec rake

Relationship to fastlane

This is an unofficial plugin and is not affiliated with fastlane or Apple. Adding VoIP support to pem itself has been requested since 2017 in fastlane/fastlane#8145; if it ever lands upstream, this plugin will be deprecated in favour of it.

License

MIT. See LICENSE.