Introduction

This guide shows you how to build and test a Swift package.

GitHub-hosted runners have a tools cache with preinstalled software, and the Ubuntu and macOS runners include the dependencies for building Swift packages. For a full list of up-to-date software and the preinstalled versions of Swift and Xcode, seeGitHub-hosted runners.

Prerequisites

You should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, seeWorkflow syntax for GitHub Actions.

We recommend that you have a basic understanding of Swift packages. For more information, seeSwift Packages in the Apple developer documentation.

Using a Swift workflow template

To get started quickly, add a workflow template to the.github/workflows directory of your repository.

GitHub provides a workflow template for Swift that should work for most Swift projects. The subsequent sections of this guide give examples of how you can customize this workflow template.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Actions.

   

3. If you already have a workflow in your repository, clickNew workflow.

4. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "swift".

5. Filter the selection of workflows by clickingContinuous integration.

6. On the "Swift" workflow, clickConfigure.

7. Edit the workflow as required. For example, change the branch on which the workflow will run.

8. ClickCommit changes.

   Theswift.yml workflow file is added to the.github/workflows directory of your repository.

Specifying a Swift version

To use a specific preinstalled version of Swift on a GitHub-hosted runner, use theswift-actions/setup-swift action. This action finds a specific version of Swift from the tools cache on the runner and adds the necessary binaries toPATH. These changes will persist for the remainder of a job. For more information, see theswift-actions/setup-swift action.

If you are using a self-hosted runner, you must install your desired Swift versions and add them toPATH.

The examples below demonstrate using theswift-actions/setup-swift action.

Using multiple Swift versions

You can configure your job to use multiple versions of Swift in a matrix.

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.name: Swifton: [push]jobs:  build:    name: Swift ${{ matrix.swift }} on ${{ matrix.os }}    strategy:      matrix:        os: [ubuntu-latest, macos-latest]        swift: ["5.2", "5.3"]    runs-on: ${{ matrix.os }}    steps:      - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf        with:          swift-version: ${{ matrix.swift }}      - uses: actions/checkout@v5      - name: Build        run: swift build      - name: Run tests        run: swift test

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.name:Swifton: [push]jobs:build:name:Swift${{matrix.swift}}on${{matrix.os}}strategy:matrix:os: [ubuntu-latest,macos-latest]swift: ["5.2","5.3"]runs-on:${{matrix.os}}steps:-uses:swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bfwith:swift-version:${{matrix.swift}}-uses:actions/checkout@v5-name:Buildrun:swiftbuild-name:Runtestsrun:swifttest

Using a single specific Swift version

You can configure your job to use a single specific version of Swift, such as5.3.3.

steps:  - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf    with:      swift-version: "5.3.3"  - name: Get swift version    run: swift --version # Swift 5.3.3

steps:-uses:swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bfwith:swift-version:"5.3.3"-name:Getswiftversionrun:swift--version# Swift 5.3.3

Building and testing your code

You can use the same commands that you use locally to build and test your code using Swift. This example demonstrates how to useswift build andswift test in a job:

steps:  - uses: actions/checkout@v5  - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf    with:      swift-version: "5.3.3"  - name: Build    run: swift build  - name: Run tests    run: swift test

steps:-uses:actions/checkout@v5-uses:swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bfwith:swift-version:"5.3.3"-name:Buildrun:swiftbuild-name:Runtestsrun:swifttest