SPM Registry Authentication#

SwifterPM (Tuist's internal SPM resolution layer) maintains two distinct authentication code paths with different credential lookup orders. Understanding which path applies — and what credentials each consults — is essential for diagnosing 401/404 failures during tuist install.

Two Auth Code Paths#

The Keychain gap for binary artifacts is a known open issue. A Keychain credential for api.github.com is never consulted when downloading a .binaryTarget URL — only registry downloads use RegistryKeychain 1.

Credential Resolution Order#

Registry packages — RegistryAuthorization.header 2#

1. SWIFTPM_REGISTRY_TOKEN env var → Bearer token
2. SWIFTPM_REGISTRY_LOGIN + SWIFTPM_REGISTRY_PASSWORD env vars → Basic/Bearer (per registry config auth type)
3. SWIFTPM_NETRC_DATA env var (inline netrc content)
4. macOS Keychain — kSecClassInternetPassword lookup by host 3
5. ~/.netrc file

Binary artifact downloads — HTTPAuthorization.header 4#

1. SWIFTPM_NETRC_DATA env var (inline netrc content)
2. ~/.netrc file
3. GITHUB_TOKEN / GH_TOKEN env var (GitHub/api.github.com hosts only) → Bearer token
4. gh auth token CLI fallback (GitHub hosts only)

Note: netrc deliberately beats the ambient GitHub token. In GitHub Actions, GITHUB_TOKEN is repo-scoped and returns HTTP 404 (not 403) for assets in a different private repo. A machine api.github.com netrc entry with broader scope should take precedence — this was fixed in PR #11528. 5

CI / Headless Configuration#

For registry packages on CI, tuist registry login writes credentials into the SPM registry configuration. It accepts both project tokens (TUIST_TOKEN) and OIDC account JWTs — the OIDC path was added in PR #9769.

For binary artifacts on CI, the recommended approaches (in order of preference):

1. SWIFTPM_NETRC_DATA — set inline netrc content as an environment variable (safe for secrets managers):

   ⧉

   SWIFTPM_NETRC_DATA="machine api.github.com login x-access-token password <token>"
   

2. ~/.netrc — write a file at $HOME/.netrc:

   ⧉

   machine api.github.com
   login x-access-token
   password <github-app-token-scoped-to-private-repo>
   

3. GITHUB_TOKEN / GH_TOKEN — only works if the token has access to the repo hosting the asset.

4. gh CLI — gh auth login before running tuist install.

Keychain credentials are not supported for binary artifact downloads 6.

Registry Configuration Loading#

RegistryConfig.load merges three sources in order:

1. Global: ~/.swiftpm/configuration/registries.json
2. Project: .swiftpm/configuration/registries.json
3. --config-path override (passed via registryConfigurationPath in PackageResolver)

The authentication section in registries.json controls whether a registry uses basic or token (bearer) auth 7. If the section is absent, swifterpm infers bearer when the netrc/Keychain login field equals "token" 8.

Key Source Files#