> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/swift.md).

# Swift

Swift - host Swift packages in Harness Artifacts

Use a **Swift** registry to publish and consume Swift packages with Swift Package Manager (SwiftPM).

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install Swift 5.9 or later with Swift Package Registry support (`swift package-registry --help`) on your local machine.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Swift registry

To create a Swift registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Swift** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

{% hint style="info" %}
**Private Swift registry**

A **Private** registry serves Swift packages only to clients that authenticate with an identity token from your Harness account.
{% endhint %}

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Swift packages from external sources when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Swift** as the **Registry type**.
7. Select **Custom** as the **Source**, then specify the **Remote registry URL** for the upstream Swift Package Registry.
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required.
9. Optionally, configure **Metadata configuration**:
   * **Metadata cache TTL (seconds)**
   * **Negative cache TTL (seconds)**
10. Select **Create** to finalize.

{% hint style="info" %}
**Metadata configuration**

**Metadata cache TTL** controls how long Harness caches Swift package metadata from the upstream before refreshing it. **Negative cache TTL** controls how long Harness caches a not-found lookup before it retries the upstream. Go to [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl) for guidance on setting these values for your use case.
{% endhint %}

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Swift Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## Swift client setup

In your Swift Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for SwiftPM.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Swift Artifact Registry, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Configure SwiftPM to use your registry, then publish and resolve packages. In the code samples, replace the values in angle brackets with your own values.

**1. Configure SwiftPM**

Point SwiftPM at your Harness registry:

```bash
swift package-registry set https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/swift
```

Authenticate with your identity token:

```bash
swift package-registry login https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/swift --token <IDENTITY_TOKEN>
```

**2. Publish the package**

Publish a package version to the registry:

```bash
swift package-registry publish <ARTIFACT_NAME> <VERSION>
```

{% hint style="warning" %}
**Swift package identity format**

`<ARTIFACT_NAME>` (the Swift package identity) must be in `scope.name` form, for example `mona.LinkedList`. Both `scope` and `name` start with a letter and can contain letters, digits, hyphens, and underscores. Harness rejects an identifier that is missing the dot, contains more than one dot, or uses other characters.
{% endhint %}

Optionally, include package metadata, and signatures if your signing policy requires them:

```bash
swift package-registry publish <ARTIFACT_NAME> <VERSION> --metadata-path metadata.json

swift package-registry publish <ARTIFACT_NAME> <VERSION> \
  --metadata-path metadata.json \
  --private-key-path private-key.der \
  --cert-chain-paths cert-chain.der
```

**3. Use the package**

Add a package-level dependency to `Package.swift`:

```swift
dependencies: [
    .package(id: "<ARTIFACT_NAME>", from: "<VERSION>"),
],
```

Add a target-level dependency:

```swift
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "<PRODUCT_NAME>", package: "<ARTIFACT_NAME>")
        ]
    )
]
```

Resolve dependencies:

```bash
swift package resolve
```

Optionally, if `Package.swift` still references dependencies by Git URL, resolve them from the registry instead:

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

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new directory with no cached Swift packages and no existing `Package.resolved` file, use SwiftPM to resolve the package you published.
2. Confirm that SwiftPM downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        swift package-registry publish <ARTIFACT_NAME> "$PACKAGE_VERSION" --metadata-path metadata.json
```

## Troubleshooting

<details>

<summary>`swift package-registry login` fails with `401` or `403`</summary>

Check that the registry URL and identity token match the ones shown in **Setup Client**. If the token expired or was revoked, generate a new one, then run `swift package-registry login` again.

</details>

<details>

<summary>`swift package-registry publish` returns `409 Conflict`</summary>

Package versions are immutable after publish. Choose a new semantic version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`swift package-registry publish` rejects `` as an invalid identifier</summary>

The package identity must be in `scope.name` form, with both parts starting with a letter and containing only letters, digits, hyphens, and underscores. Correct the identifier and publish again.

</details>

<details>

<summary>`swift package resolve` cannot find the package, or resolves an older version</summary>

Check that the package identity and version in `Package.swift` match the values you used when you published the package. Also, check that the registry URL you configured with `swift package-registry set` is correct, then clear `Package.resolved` and resolve again.

</details>

<details>

<summary>Setup Client omits publish instructions for a Swift upstream proxy</summary>

An upstream proxy registry is pull-only, so **Setup Client** does not show publish instructions for it. Publish your package to a standard Swift registry instead, or let the upstream proxy cache packages fetched from the remote registry.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
