Building and testing Rust

Introduction

This guide shows you how to build, test, and publish a Rust package.

GitHub-hosted runners have a tools cache with preinstalled software, which includes the dependencies for Rust. For a full list of up-to-date software and the preinstalled versions of Rust, see GitHub 호스팅 실행기 정보.

Prerequisites

You should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, see GitHub Actions에 대한 워크플로 구문.

We recommend that you have a basic understanding of the Rust language. For more information, see Getting started with Rust.

Using a Rust workflow template

빠르게 시작하려면 워크플로 템플릿을 리포지토리의 .github/workflows 디렉터리에 추가합니다.

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

1. GitHub에서 리포지토리의 기본 페이지로 이동합니다.

2. 리포지토리 이름 아래에서 작업을 클릭합니다.

   

3. 리포지토리에 워크플로가 이미 있는 경우 새 워크플로를 클릭합니다.

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

5. Filter the selection of workflows by clicking Continuous integration.

6. On the "Rust - by GitHub Actions" workflow, click Configure.

   
   If you don't find the "Rust - by GitHub Actions" workflow template, copy the following workflow code to a new file called rust.yml in the .github/workflows directory of your repository.
   YAML

   name: Rust
   
   on:
     push:
       branches: [ "main" ]
     pull_request:
       branches: [ "main" ]
   
   env:
     CARGO_TERM_COLOR: never
   
   jobs:
     build:
   
       runs-on: ubuntu-latest
   
       steps:
       - uses: actions/checkout@v4
       - name: Build
         run: cargo build --verbose
       - name: Run tests
         run: cargo test --verbose
   

7. Edit the workflow as required. For example, change the version of Rust.

8. Click Commit changes.

Specifying a Rust version

GitHub-hosted runners include a recent version of the Rust toolchain. You can use rustup to report on the version installed on a runner, override the version, and to install different toolchains. For more information, see The rustup book.

This example shows steps you could use to setup your runner environment to use the nightly build of rust and to report the version.

      - name: Temporarily modify the rust toolchain version
        run: rustup override set nightly
      - name: Output rust version for educational purposes
        run: rustup --version

      - name: Temporarily modify the rust toolchain version
        run: rustup override set nightly
      - name: Output rust version for educational purposes
        run: rustup --version

Caching dependencies

You can cache and restore dependencies using the Cache action. This example assumes that your repository contains a Cargo.lock file.

      - name: Cache
      - uses: actions/cache@v3
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

      - name: Cache
      - uses: actions/cache@v3
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

If you have custom requirements or need finer controls for caching, you should explore other configuration options for the cache action. For more information, see 워크플로 속도를 높이기 위한 종속성 캐싱.

Building and testing your code

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

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        BUILD_TARGET: [release] # refers to a cargo profile
    outputs:
      release_built: ${{ steps.set-output.outputs.release_built }}
    steps:
      - uses: actions/checkout@v4
      - name: Build binaries in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo build --profile ${{ matrix.BUILD_TARGET }}
      - name: Run tests in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo test --profile ${{ matrix.BUILD_TARGET }}

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        BUILD_TARGET: [release] # refers to a cargo profile
    outputs:
      release_built: ${{ steps.set-output.outputs.release_built }}
    steps:
      - uses: actions/checkout@v4
      - name: Build binaries in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo build --profile ${{ matrix.BUILD_TARGET }}
      - name: Run tests in "${{ matrix.BUILD_TARGET }}" mode
        run: cargo test --profile ${{ matrix.BUILD_TARGET }}

The release keyword used in this example corresponds to a cargo profile. You can use any profile you have defined in your Cargo.toml file.

Publishing your package or library to crates.io

Once you have setup your workflow to build and test your code, you can use a secret to login to crates.io and publish your package.

      - name: Login into crates.io
        run: cargo login ${{ secrets.CRATES_IO }}
      - name: Build binaries in "release" mode
        run: cargo build -r
      - name: "Package for crates.io"
        run: cargo package # publishes a package as a tarball
      - name: "Publish to crates.io"
        run: cargo publish # publishes your crate as a library that can be added as a dependency

      - name: Login into crates.io
        run: cargo login ${{ secrets.CRATES_IO }}
      - name: Build binaries in "release" mode
        run: cargo build -r
      - name: "Package for crates.io"
        run: cargo package # publishes a package as a tarball
      - name: "Publish to crates.io"
        run: cargo publish # publishes your crate as a library that can be added as a dependency

If there are any errors building and packaging the crate, check the metadata in your manifest, Cargo.toml file, see The Manifest Format. You should also check your Cargo.lock file, see Cargo.toml vs Cargo.lock.

Packaging workflow data as artifacts

After a workflow completes, you can upload the resulting artifacts for analysis or to use in another workflow. You could add these example steps to the workflow to upload an application for use by another workflow.

      - name: Upload release artifact
        uses: actions/upload-artifact@v3
        with:
          name: <my-app>
          path: target/${{ matrix.BUILD_TARGET }}/<my-app>

      - name: Upload release artifact
        uses: actions/upload-artifact@v3
        with:
          name: <my-app>
          path: target/${{ matrix.BUILD_TARGET }}/<my-app>

To use the uploaded artifact in a different job, ensure your workflows have the right permissions for the repository, see 자동 토큰 인증. You could use these example steps to download the app created in the previous workflow and publish it on GitHub.

      - uses: actions/checkout@v4
      - name: Download release artifact
        uses: actions/download-artifact@v3
        with:
          name: <my-app>
          path: ./<my-app>
      - name: Publish built binary to GitHub releases
      - run: |
          gh release create --generate-notes ./<my-app>/<my-project>#<my-app>

      - uses: actions/checkout@v4
      - name: Download release artifact
        uses: actions/download-artifact@v3
        with:
          name: <my-app>
          path: ./<my-app>
      - name: Publish built binary to GitHub releases
      - run: |
          gh release create --generate-notes ./<my-app>/<my-project>#<my-app>