Use the HexSign Fetch Signing Material Bitrise Step

The hexsign-fetch-signing-material Step downloads the certificate (.p12 + password) and/or provisioning profile (.mobileprovision) you've stored in HexSign, places them on disk, and exposes the resulting paths as env vars for downstream Steps like certificate-and-profile-installer, xcode-archive, and fastlane.

Two fetch modes

By id

Set certificate_id / profile_id to a HexSign UUID. Best when you want a specific artefact pinned across runs.

By filter (rotation-proof)

Set certificate_type + team_id to download every matching cert in that Apple Developer team, or bundle_id (optionally with team_id) to download every profile for that bundle. Survives certificate / profile rotation. No CI variable to update when an artefact is regenerated.

What you need

• A service credential with hexsign-api/read scope. Provision it under Settings → CLI Tokens in the HexSign dashboard; the secret is shown exactly once.
• HEXSIGN_CLIENT_ID and HEXSIGN_CLIENT_SECRET configured as secret env vars in the Bitrise workflow editor (never paste them into bitrise.yml).
• At least one of certificate_id, certificate_type, profile_id, or bundle_id. The Step covers fetch-cert-only, fetch-profile-only, and fetch-both flows in a single configuration.

Add it to your workflow (by id)

steps:
  - hexsign-fetch-signing-material@0:
      inputs:
        - certificate_id: $HEXSIGN_CERT_ID
        - profile_id:     $HEXSIGN_PROFILE_ID
        - client_id:      $HEXSIGN_CLIENT_ID
        - client_secret:  $HEXSIGN_CLIENT_SECRET
  - certificate-and-profile-installer@1:
      inputs:
        - certificate_url:         file://$HEXSIGN_CERTIFICATE_PATH
        - provisioning_profile_url: file://$HEXSIGN_PROFILE_PATH
        # Read the .password file in a script step and feed it in via env.
  - xcode-archive@5: {}

Or by certificate type + bundle id (rotation-proof)

steps:
  - hexsign-fetch-signing-material@0:
      inputs:
        - certificate_type: DISTRIBUTION
        - bundle_id:        com.example.app
        - team_id:          $HEXSIGN_TEAM_ID
        - client_id:        $HEXSIGN_CLIENT_ID
        - client_secret:    $HEXSIGN_CLIENT_SECRET

In bulk mode the Step may write more than one .p12/.password pair or more than one .mobileprovision. The singular outputs (HEXSIGN_CERTIFICATE_PATH, HEXSIGN_PROFILE_PATH) hold the first match for backwards compatibility; the plural outputs (HEXSIGN_CERTIFICATE_PATHS, HEXSIGN_PROFILE_PATHS) hold every file as a newline-separated list (iterate them from a script step when you need to install all of them).

Inputs

certificate_id

HexSign certificate UUID (single-cert mode). Mutually exclusive with certificate_type.

certificate_type

Apple cert type (e.g. DISTRIBUTION). Downloads every matching certificate. Requires team_id. Mutually exclusive with certificate_id.

profile_id

HexSign provisioning profile UUID (single-profile mode). Mutually exclusive with bundle_id.

bundle_id

App bundle identifier: downloads every matching .mobileprovision. Pair with team_id to scope across linked Apple accounts. Mutually exclusive with profile_id.

team_id

Apple Developer team identifier (10-character prefix, e.g. ABCDE12345). Required with certificate_type; optional but recommended with bundle_id when multiple Apple accounts are linked.

client_id / client_secret

Required. Defaults to $HEXSIGN_CLIENT_ID and $HEXSIGN_CLIENT_SECRET so a typical setup needs no input override.

scopes

Optional. Space-separated OAuth scopes. Leave empty to use the CLI default.

output_dir

Where to write downloaded files. Defaults to $BITRISE_DEPLOY_DIR so artefacts are picked up by the deploy Step automatically.

keychain

Optional, macOS only. Path to a keychain to create and import the downloaded certificate(s) into, configured so codesign can use them without an interactive prompt. No manual security calls or certificate-and-profile-installer needed for the cert. The keychain must not already exist. Echoed back as the HEXSIGN_KEYCHAIN_PATH output.

install_profile

Optional, macOS only. Any non-empty value installs each downloaded .mobileprovision into ~/Library/MobileDevice/Provisioning Profiles as <UUID>.mobileprovision, where Xcode discovers it. No manual install step. The install destinations are exposed as HEXSIGN_INSTALLED_PROFILE_PATH / HEXSIGN_INSTALLED_PROFILE_PATHS.

cli_version

hexsign-cli release tag (e.g. v0.4.2) or latest. Pin to a tag for hermetic builds; the Step verifies SHA-256 against the release's signed checksums.txt either way.

Outputs

HEXSIGN_CERTIFICATE_PATH

Absolute path to the first .p12. Empty when no certificate was fetched.

HEXSIGN_CERTIFICATE_PASSWORD_PATH

Absolute path to the .password file that sits next to the first .p12. Read it in a script step before handing it to certificate-and-profile-installer.

HEXSIGN_PROFILE_PATH

Absolute path to the first .mobileprovision. Empty when no profile was fetched.

HEXSIGN_CERTIFICATE_PATHS

Newline-separated list of every downloaded .p12 path. Populated in bulk mode (certificate_type).

HEXSIGN_CERTIFICATE_PASSWORD_PATHS

Newline-separated list of every downloaded .password path. Populated in bulk mode.

HEXSIGN_PROFILE_PATHS

Newline-separated list of every downloaded .mobileprovision path. Populated in bulk mode (bundle_id).

HEXSIGN_KEYCHAIN_PATH

Path to the keychain the certificate(s) were imported into. Set only when the keychain input was used and a certificate was fetched; empty otherwise.

HEXSIGN_INSTALLED_PROFILE_PATH / HEXSIGN_INSTALLED_PROFILE_PATHS

Path to the first profile installed for Xcode, and the newline-separated list of all of them. Each file's basename is the profile UUID. Set only when the install_profile input was used.

How auth works

The Step exports HEXSIGN_CLIENT_ID and HEXSIGN_CLIENT_SECRET into the CLI's environment, which puts the binary in machine mode. The CLI exchanges them for an access token against identity.hexsign.net/oauth2/token and uses it for the download requests. Both env vars are masked in Bitrise logs because they're declared as secrets.