Use the HexSign GitLab CI/CD component

The HexSign GitLab CI/CD component installs the hexsign binary on a GitLab runner and downloads the certificate (.p12 + password) and/or provisioning profile (.mobileprovision) you've stored in HexSign. Add it to .gitlab-ci.yml with a single include: block, then let a later job run security import and xcodebuild against the freshly fetched material.

Two components

setup

Installs the CLI, verifies its SHA-256 against the release's checksums.txt, and uploads the binary as a short-lived job artifact. Use it when you want to compose your own pipeline and call hexsign directly from a build job.

fetch

One-shot: installs the CLI and downloads the requested signing material into a directory, published as a job artifact for downstream stages. Use it when you want a turnkey job and no extra wiring.

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/CD 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 masked, protected CI/CD variables (Settings → CI/CD → Variables). Never paste them into .gitlab-ci.yml.
• At least one of certificate_id, certificate_type, profile_id, or bundle_id. The component covers fetch-cert-only, fetch-profile-only, and fetch-both flows in one configuration.

Add the fetch component (by id)

include:
  - component: $CI_SERVER_FQDN/hexsign/hexsign-gitlab-component/fetch@~latest
    inputs:
      certificate_id: $HEXSIGN_CERT_ID
      profile_id:     $HEXSIGN_PROFILE_ID
      output_dir:     build/sign

stages:
  - signing
  - build

xcodebuild:
  stage: build
  needs: [hexsign-fetch]
  dependencies: [hexsign-fetch]
  script:
    - security import build/sign/*.p12 -P "$(cat build/sign/*.password)"
    - xcodebuild -scheme MyApp archive

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

include:
  - component: $CI_SERVER_FQDN/hexsign/hexsign-gitlab-component/fetch@~latest
    inputs:
      certificate_type: DISTRIBUTION
      bundle_id:        com.example.app
      team_id:          $HEXSIGN_TEAM_ID
      output_dir:       build/sign

In bulk mode the component may write more than one .p12/.password pair or more than one .mobileprovision into output_dir. The whole directory is uploaded as a job artifact, so a downstream job picks them all up by attaching the artifact with dependencies: or needs:.

Install the CLI only with setup

When you'd rather call the CLI yourself, include the setup component instead. It uploads .hexsign/hexsign as an artifact that any later job can invoke directly.

include:
  - component: $CI_SERVER_FQDN/hexsign/hexsign-gitlab-component/setup@~latest
    inputs:
      cli_version: latest

build:
  needs: [hexsign-setup]
  dependencies: [hexsign-setup]
  script:
    - ./.hexsign/hexsign certificates download "$HEXSIGN_CERT_ID" --output-dir build/sign

fetch inputs

cli_version

hexsign-cli release tag (e.g. v0.4.2) or latest. Pin to a tag for hermetic builds; the component 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. The directory is published as a job artifact.

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. Requires a macOS runner, so set image/tags accordingly.

install_profile

Optional boolean, macOS only. When true, each downloaded profile is installed into ~/Library/MobileDevice/Provisioning Profiles, where Xcode discovers it. No manual install step. Requires a macOS runner, so set image/tags accordingly.

artifact_expire_in

How long the downloaded signing material lives as a CI artifact. Defaults to 1 hour. Keep it short: artifacts contain .p12 and .password files.

scopes

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

job_name / stage / image

Optional overrides for the generated job's name, pipeline stage, and Docker image. Defaults: hexsign-fetch, .pre, and alpine:latest.

How auth works

The component 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. Mark both variables as Masked so they're redacted from job logs, and Protected so they're only exposed to pipelines on protected branches and tags.