Swift Package Registry

Tuist provides a Swift package registry that lets you host private Swift packages, control access, and integrate seamlessly with Swift Package Manager.

Overview

The Tuist Registry provides:

Private Packages

Host proprietary Swift packages securely

Team Access Control

Manage who can access your packages

Version Management

Publish and manage package versions

Tuist Registry follows the official Swift Package Registry specification, ensuring compatibility with Swift Package Manager.

Why Use a Private Registry?

Benefits

Keep code private

Proprietary business logic
Internal tools and utilities
Company-specific frameworks
Avoid exposing code publicly

Better than Git dependencies

Registry packages:

Immutable versions
Faster resolution
Better caching
No Git history bloat

Git dependencies:

Require full repository clone
Slower resolution
Cache invalidation issues
Expose full Git history

Enterprise control

Audit package downloads
Control who accesses what
Require authentication
Track usage analytics

Getting Started

Setup Authentication

Authenticate with Tuist

tuist auth

Configure registry

Link your project to enable registry access:

tuist project create

Setup registry in Swift Package Manager

Configure SPM to use Tuist Registry:

tuist registry setup

This configures ~/.swiftpm/configuration/registries.json

Publish a Package

Prepare your package

Ensure your package has a valid Package.swift:

// Package.swift
let package = Package(
    name: "MyLibrary",
    platforms: [.iOS(.v15)],
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]
        ),
    ],
    targets: [
        .target(name: "MyLibrary"),
    ]
)

Tag a version

Create a semantic version tag:

git tag 1.0.0
git push --tags

Publish to registry

tuist registry publish

Tuist will:

Validate the package
Upload to the registry
Make it available to your team

You can also publish from CI to automate package distribution.

Using Registry Packages

In Package.swift

Add registry packages as dependencies:

Package.swift

import PackageDescription

let package = Package(
    name: "MyApp",
    dependencies: [
        // Tuist registry package
        .package(
            id: "com.acme.MyLibrary",
            from: "1.0.0"
        ),
        
        // Traditional Git dependency for comparison
        // .package(
        //     url: "https://github.com/acme/MyLibrary",
        //     from: "1.0.0"
        // )
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: ["MyLibrary"]
        ),
    ]
)

In Tuist Projects

Use registry packages in your Tuist project:

Project.swift

import ProjectDescription

let project = Project(
    name: "MyApp",
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                .package(product: "MyLibrary", type: .runtime)
            ]
        ),
    ],
    packages: [
        .remote(
            id: "com.acme.MyLibrary",
            version: "1.0.0"
        )
    ]
)

Resolution

Swift Package Manager will:

Check Tuist Registry first
Download the package archive
Cache it locally
Link it to your project

Package Scopes

Organize packages with scopes (namespaces):

com.acme.networking     - Networking library
com.acme.analytics      - Analytics SDK
com.acme.ui-components  - UI component library

Naming Convention

Use reverse-domain notation:

Scope: Company or organization (com.acme)
Name: Package name (networking)
Full ID: com.acme.networking

Package IDs must be unique within your organization. Choose meaningful, descriptive names.

Version Management

Semantic Versioning

Follow SemVer for version numbers:

Major (1.0.0): Breaking changes
Minor (1.1.0): New features, backward compatible
Patch (1.0.1): Bug fixes, backward compatible

# Publish major version
git tag 2.0.0
tuist registry publish

# Publish minor version  
git tag 1.1.0
tuist registry publish

# Publish patch version
git tag 1.0.1
tuist registry publish

Version Constraints

Consumers specify version requirements:

Exact Version
Range
Up to Next Major
Branch

.package(id: "com.acme.MyLibrary", exact: "1.0.0")

Use when you need a specific version.

.package(id: "com.acme.MyLibrary", from: "1.0.0")

Allows minor and patch updates (e.g., 1.0.0 to 1.9.9).

.package(
    id: "com.acme.MyLibrary",
    "1.0.0"..<"2.0.0"
)

Prevent breaking changes.

.package(id: "com.acme.MyLibrary", branch: "main")

For development only, not recommended for production.

List Versions

View all published versions:

tuist registry list com.acme.MyLibrary

Output:

Available versions for com.acme.MyLibrary:
0.0 (latest)
2.1
2.0
1.0
0.0

Access Control

Authentication

Registry packages require authentication:

# Login
tuist auth

# Logout
tuist auth logout

Credentials are stored securely in your system keychain.

Team Access

Control who can access packages:

Organization members: Automatic access to all packages
External collaborators: Grant specific package access
Public packages: Anyone can download (optional)

CI/CD Authentication

Use tokens for CI authentication:

- name: Setup Tuist Registry
  run: |
    tuist registry setup
  env:
    TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}

Generate CI tokens in Tuist Cloud under Settings > Tokens.

Publishing from CI

Automate package releases:

name: Publish Package
on:
  push:
    tags:
      - '*.*.*'

jobs:
  publish:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Publish to registry
        run: tuist registry publish
        env:
          TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}

Registry Analytics

Track package usage in Tuist Cloud:

Download counts per version
Most popular packages in your organization
Active users downloading packages
Version adoption rates

Example Insights

com.acme.networking
  Downloads (30 days): 1,247
  Active users: 23
  Latest version: 2.1.0 (78% adoption)
  
Version breakdown:
  2.1.0: 975 downloads
  2.0.0: 198 downloads
  1.9.0: 74 downloads

Migration from Git Dependencies

Switch existing packages to the registry:

Publish package to registry

cd MyLibrary
git tag 1.0.0
tuist registry publish

Update consumers

Change from:

.package(
    url: "https://github.com/acme/MyLibrary",
    from: "1.0.0"
)

To:

.package(
    id: "com.acme.MyLibrary",
    from: "1.0.0"
)

Test resolution

swift package resolve

Verify the package is fetched from the registry.

Remove Git dependency (optional)

You can archive the Git repository or keep it for open-source contributions.

Best Practices

Use semantic versioning

Follow SemVer strictly
Document breaking changes
Use major versions for breaking changes
Avoid breaking changes in minor/patch releases

Automate publishing

Publish from CI on tag push
Run tests before publishing
Validate package structure
Generate changelogs automatically

Document packages

Maintain a comprehensive README
Include usage examples
Document breaking changes
Keep a CHANGELOG.md

Organize with scopes

Use consistent naming
Group related packages
Separate by domain (networking, UI, analytics)
Use company/org prefix

Troubleshooting

Package not found

Possible causes:

Package not published yet
Registry not configured
Authentication expired

Solutions:

Verify package is published: tuist registry list
Run tuist registry setup again
Re-authenticate: tuist auth

Publishing fails

Possible causes:

Invalid Package.swift
Missing git tag
Version already exists

Solutions:

Validate package: swift build
Check git tags: git tag -l
Use a new version number

Authentication issues in CI

Possible causes:

Token not set
Token expired
Wrong environment variable

Solutions:

Set TUIST_TOKEN environment variable
Regenerate token in Tuist Cloud
Verify token has correct permissions

Registry Specification

Tuist Registry implements the Swift Package Registry Service Specification.

Supported Features

✅ Package publication
✅ Version listing
✅ Package download
✅ Package metadata
✅ Authentication
✅ Scope-based organization

Future Enhancements

Package signing and verification
Mirror repositories
Dependency scanning
Vulnerability detection

Pricing

Registry usage is included in Tuist Cloud plans:

Free: Up to 5 packages
Team: Unlimited packages
Enterprise: Unlimited packages + advanced analytics

Contact sales for custom registry requirements or on-premises deployment.

Next Steps

Binary Caching

Speed up builds with smart caching

Build Insights

Monitor build performance

Get Started

Core Concepts

Features

Guides

Documentation Index

​Overview

Private Packages

Team Access Control

Version Management

​Why Use a Private Registry?

​Benefits

​Getting Started

​Setup Authentication

​Publish a Package

​Using Registry Packages

​In Package.swift

​In Tuist Projects

​Resolution

​Package Scopes

​Naming Convention

​Version Management

​Semantic Versioning

​Version Constraints

​List Versions

​Access Control

​Authentication

​Team Access

​CI/CD Authentication

​Publishing from CI

​Registry Analytics

​Example Insights

​Migration from Git Dependencies

​Best Practices

​Troubleshooting

​Registry Specification

​Supported Features

​Future Enhancements

​Pricing

​Next Steps

Binary Caching

Build Insights

Build docs developers (and LLMs) love

Overview

Why Use a Private Registry?

Benefits

Getting Started

Setup Authentication

Publish a Package

Using Registry Packages

In Package.swift

In Tuist Projects

Resolution

Package Scopes

Naming Convention

Version Management

Semantic Versioning

Version Constraints

List Versions

Access Control

Authentication

Team Access

CI/CD Authentication

Publishing from CI

Registry Analytics

Example Insights

Migration from Git Dependencies

Best Practices

Troubleshooting

Registry Specification

Supported Features

Future Enhancements

Pricing

Next Steps