Swift Registry

Cloudsmith provides public & private registries for Swift

The Swift Package Manager is a tool for managing the distribution of Swift code. It's integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. Cloudsmith is fully compatible as a Swift registry.

With Swift, developers can create, share, and manage packages for their projects.

For more information on Swift, please see:

• Swift: The official website for Swift
• The Swift registry  is a HTML catalog of Swift Packages which helps direct users to third-party Git repositories. It does not host swift packages.
• The Swift package manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.
• Creating a Swift package: Creating a Swift package

In the following examples:

Configure Cloudsmith as your Swift Registry

Create a Cloudsmith Repository

If you haven't already, create a repository in Cloudsmith where you'll publish your package. Note down the repository URL, which should resemble:

https://swift.cloudsmith.io/WORKSPACE/REPOSITORY

Replace WORKSPACE with your Cloudsmith Workspace name and REPOSITORY with the name of your repository.

Creating a Swift package

If you don't have a sample package to test this, use swift package init to create a new one:

mkdir swift_sample
cd swift_sample
swift package init --name PACKAGE_NAME --type executable

A successful run will output:

Creating executable package: your-package
Creating Package.swift
Creating .gitignore
Creating Sources/
Creating Sources/main.swift

Now, package its assets using the swift package archive-source command:

swift package archive-source

The terminal will output Created PACKAGE_NAME.zip if successful.

Configure Cloudsmith as your Swift Registry

Use Swift version 5.9 or above (verify your version with swift -version) to publish Swift package to Cloudsmith using the Swift Package Manager. Then, set your Cloudsmith repository for the project:

swift package-registry set https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/

This creates a configuration file at .swiftpm/configuration/registries.jsonthat looks like this:

{
  "authentication" : {

  },
  "registries" : {
    "[default]" : {
      "supportsAvailability" : false,
      "url" : "https://swift.cloudsmith.io/cloudsmith-test/buildkite-demo"
    }
  },
  "version" : 1

Note

📘 Instead of configuring the registry per-project, you can set it globally using the --global flag. This is useful for configuring a build machine or your main development environment.

bash

swift package-registry set --global "https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/"

Then, get your API_TOKEN and login to your private Cloudsmith Swift registry with:

swift package-registry login https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/ --username USERNAME --password API_TOKEN

Upload a Package

Upload using Swift Package Manager

A Swift package consists of Swift source files and a manifest file. The manifest file, called Package.swift, defines the package’s name and its contents using the PackageDescription module.

Navigate to the Swift project directory that contains the Package.swift file for your package. Replace SCOPE, PACKAGE_NAME and VERSION with the scope of the package, package name and package version respectively.

swift package-registry publish SCOPE.PACKAGE_NAME VERSION

Swift scopes

In Swift, scope are namespaces for package names. You can publish any scope to your Cloudsmith repository. Package scopes are case-insensitive (for example, mona ≍ MONA).

Version numbers should follow semantic versioning.

Upload Verification

After publishing, You should receive a confirmation message similar to the following:

SCOPE.PACKAGE_NAME version VERSION was successfully published to https://swift.cloudsmith.io/WORKSPACE/REPOSITORY and is available at 'https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/SCOPE/PACKAGE_NAME/VERSION'

You can verify that your package is available in your Cloudsmith repository by navigating to the repository URL in your browser or using the Cloudsmith CLI.

Alternative example: from source code

In the next steps we cover how to package an existing swift project from its source code in GitHub, and then upload it to a Cloudsmith repository. For this example, we'll be using Alamofire: a popular HTTP networking library written in Swift.

Download its source code and checkout version 5.9.1:

cd .. # get back to the previous dir
git clone https://github.com/Alamofire/Alamofire.git --depth 1
cd Alamofire
git fetch --depth 1 origin tag 5.9.1
git checkout 5.9.1

To publish a package, you need to create a package-metadata.json file. This file provides essential details about the package.

Create this file in the root of the Alamofire directory and paste in the following content:

{
    "author": {
        "name": "Alamofire Software Foundation",
        "email": "info@alamofire.org",
        "organization": {
            "name": "Alamofire Software Foundation"
        }
    },
    "description": "Elegant HTTP Networking in Swift",
    "licenseURL": "https://github.com/Alamofire/Alamofire/blob/master/LICENSE",
    "readmeURL": "https://github.com/Alamofire/Alamofire/blob/master/README.md",
    "repositoryURLs": [
        "https://github.com/Alamofire/Alamofire.git"
    ]
}

You are ready to publish the package to your Cloudsmith Registry. Follow the previous steps to configure and login to your registry (no need to run it again if you executed the previous example) and replace WORKSPACE and REPOSITORY with your own:

# swift package-registry set "https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/"
# swift package-registry login https://swift.cloudsmith.io/WORKSPACE/REPOSITORY/ --username USERNAME --password API-TOKEN
swift package-registry publish alamofire.alamofire 5.9.1 --metadata-path ./package-metadata.json

Done! You've successfully published your Swift package to a Cloudsmith registry. You can now view the package in your Cloudsmith web app.

Upload via the Cloudsmith CLI

CLI Install and Auth

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface documentation:

• Installation.
• Authentication.

To upload via the Cloudsmith CLI (or via API), you'll need to generate your package first:

swift package archive-source

This will generate a zip file named Alamofire.zip that you can upload. Use the previous command to upload your new swift package via the Cloudsmith CLI and rememver to use a different version number (for example 5.9.2):

cloudsmith push swift WORKSPACE/REPOSITORY PACKAGE_NAME.zip --name PACKAGE_NAME --version VERSION --scope SCOPE

The next output will be displayed:

Checking swift package upload parameters ... OK
Checking Alamofire.zip file upload parameters ... OK
Requesting file upload for Alamofire.zip ... OK
Uploading Alamofire.zip:  [####################################]  100%
Creating a new swift package ... OK
Created: demo-docs/awesome-repo/alamofirezip-z54v (DIElCIDoFtvd)

Synchronising alamofirezip-z54v:  [####################################]  100%  Completed / Fully Synchronised                      

Package synchronised successfully in 51.71964 second(s)!

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app. Generate your package first using swift package archive-source.

Download / Install a Package

Now, let's see how to use the package from your registry in a new project:

1. Create a new directory for a sample project and cd into it.

cd ..
mkdir MySwiftApp && cd MySwiftApp
swift package init --type executable

2. Configure the Registry for the New Project: following the steps described above to configure Swift to use your Cloudsmith registry URL and then login to it.

3. Add your project dependencies:

Swift dependencies file

Package dependencies are declared in the Package.swift file. Edit the Package.swift file in your application project folder to update the package dependencies to be used by your project:

1. In the dependencies section of Package.swift, add the package you want to use by adding its package identifier. The package identifier consists of the scope and package name separated by a period. See the code snippet following a later step for an example.
2. In the targets section of Package.swift, add the targets that will need to use the dependency.

The following is an example showing configured dependencies and targets sections in a Package.swift file to include Alamofire as a dependency:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MySwiftApp",
    dependencies: [
        .package(id: "alamofire.alamofire", from: "5.9.1") // Add this line
    ],
    targets: [
        .executableTarget(
            name: "MySwiftApp",
            dependencies: [
                .product(name: "Alamofire", package: "alamofire.alamofire") // And this one
            ]
        ),
    ]
)

After this, use the --replace-scm-with-registry flag to prioritize fetching from your registry instead of Git.

swift package --replace-scm-with-registry resolve

You will see output indicating that Swift is downloading alamofire.alamofire directly from your Cloudsmith registry. You should see the following printed out when resolving dependancies

Computing version for alamofire.alamofire
Computed alamofire.alamofire at 5.9.2 (1.84s)
Fetching alamofire.alamofire
warning: 'alamofire.alamofire': alamofire.alamofire version 5.9.2 source archive from https://swift.cloudsmith.io/demo-docs/awesome-repo is not signed
Fetched alamofire.alamofire from cache (4.07s)

Swift registry resolve

📘 Using id: in your Package.swift is powerful. When you run resolve with the flag, Swift Package Manager will first try to find a matching version in your configured registry. If it fails, it can fall back to the Git repository specified in the package-metadata.json file. This provides a robust, hybrid approach.

Downloading a large repository like Alamofire can take a significant amount of time, as you're cloning the entire history. Pulling a package from a registry is much faster. You only download a lightweight source archive (.zip) for the specific version you need, drastically reducing download times and CI/CD pipeline durations.

For a more detailed overview of Package Registries usage with Swift, visit their docs.

Resetting your registry configuration

To reset your configuration:

swift package-registry unset

Or simply delete the registries.json files from your project and/or home directory:

rm -f ./.swiftpm/configuration/registries.json

To force Swift to re-resolve all your dependencies from scratch the next time you build or run your project and clear out the global Swift Package Manager cache on your machine, run:

swift package reset
swift package purge-cache

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

You can configure to proxy a private or public swift registry you wish to use for packages that are not available in your current Cloudsmith repository e.g. you can point to another Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Note

There is currently no public swift repository. HTML catalogs of Swift Packages such as Swift Package Registry that point to third-party Git repositories do not host any actual packages and so can't be added as an upstream.

Please see our Upstream Proxying documentation for further instructions.

Key Signing Support

Troubleshooting

Please see the Troubleshooting page for further help and information.