Use the HexSign GitLab CI/CD component

The [HexSign GitLab CI/CD component](https://gitlab.com/hexsign/hexsign-gitlab-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](https://dashboard.hexsign.net); 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: IOS_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. `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`. The directory is published as a job artifact.

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.