Use the HexSign CircleCI orb

The [HexSign CircleCI orb](https://circleci.com/developer/orbs/orb/hexsign/hexsign) 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_workspace`s 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](https://dashboard.hexsign.net); the secret is shown exactly once.
• A [CircleCI context](https://circleci.com/docs/contexts/) (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: IOS_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. `IOS_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.

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.