Use the HexSign CircleCI orb

The HexSign CircleCI orb installs the hexsign binary on a runner and downloads the certificate (.p12 + password) and/or provisioning profile (.mobileprovision) you've stored in HexSign. Add hexsign/hexsign to the orbs: block of .circleci/config.yml, then either call the ready-made fetch job or compose the individual commands into a job you already have.

Commands and a job

hexsign/install

Installs the CLI, verifies its SHA-256 against the release's checksums.txt, and puts the binary on $PATH. Drop it into any job that needs to call hexsign directly.

hexsign/certificates_download

Downloads one certificate by id, or every certificate of a type for a team_id (bulk mode). A no-op when neither is set.

hexsign/profiles_download

Downloads one profile by id, or every profile for a bundle_id (bulk mode). A no-op when neither is set.

hexsign/fetch

One-shot job: runs install + both download commands, then persist_to_workspaces the output directory so a downstream macOS job can attach it.

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 pipeline 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.
• A CircleCI context (Organization Settings → Contexts) holding HEXSIGN_CLIENT_ID and HEXSIGN_CLIENT_SECRET. Attach it to the workflow. Never paste secrets into .circleci/config.yml.
• At least one of certificate_id, certificate_type, profile_id, or bundle_id. The orb covers fetch-cert-only, fetch-profile-only, and fetch-both flows in one configuration.

Use the fetch job

version: 2.1

orbs:
  hexsign: hexsign/hexsign@1.0.0

workflows:
  release:
    jobs:
      - hexsign/fetch:
          context: hexsign
          certificate_id: $HEXSIGN_CERT_ID
          profile_id:     $HEXSIGN_PROFILE_ID
          output_dir:     build/sign
      - archive:
          requires: [hexsign/fetch]

The archive job then runs attach_workspace and finds the downloaded files under build/sign, ready for security import and xcodebuild.

Or compose into an existing macOS job

If you'd rather not have a separate job and the workspace round-trip, install the CLI and call the download commands inline.

jobs:
  archive:
    macos:
      xcode: 16.4.0
    steps:
      - checkout
      - hexsign/install
      - hexsign/certificates_download:
          id: $HEXSIGN_CERT_ID
          output_dir: build/sign
      - hexsign/profiles_download:
          id: $HEXSIGN_PROFILE_ID
          output_dir: build/sign
      - run: xcodebuild -scheme MyApp archive
workflows:
  release:
    jobs:
      - archive:
          context: hexsign

Bulk mode (rotation-proof)

- hexsign/fetch:
    context: hexsign
    certificate_type: DISTRIBUTION
    team_id:          ABCDE12345
    bundle_id:        com.example.app
    output_dir:       build/sign

This downloads every distribution certificate for the team and every profile attached to that bundle. No UUIDs to update when a cert or profile rotates.

fetch inputs

cli_version

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

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.

output_dir

Where to write downloaded files. Defaults to build/sign. Persisted to the CircleCI workspace.

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. Needs a macOS executor (override the default executor accordingly). Available on both the fetch job and the hexsign/certificates_download command.

install_profile

Optional boolean, macOS only. When true, each downloaded profile is installed into ~/Library/MobileDevice/Provisioning Profiles, where Xcode discovers it. Needs a macOS executor. Available on both the fetch job and the hexsign/profiles_download command (as install).

workspace_root

Root passed to persist_to_workspace. Defaults to . so a downstream job finds output_dir at the same relative path after attach_workspace.

How auth works

The orb reads HEXSIGN_CLIENT_ID and HEXSIGN_CLIENT_SECRET from the job environment, which puts the CLI in machine mode. The binary exchanges them for an access token against identity.hexsign.net/oauth2/token and uses it for the download requests. Storing them in a CircleCI context (rather than plain project env vars) lets you restrict which workflows (and which teams) can use the credential.