upload-rust-binary-action

GitHub Action for building and uploading Rust binary to GitHub Releases.

• Usage
  • Inputs
  • Outputs
  • Example workflow: Basic usage
  • Example workflow: Basic usage (multiple platforms)
  • Example workflow: Customize archive name
  • Example workflow: Build with different features on different platforms
  • Example workflow: Cross-compilation
    • cross
    • setup-cross-toolchain-action
    • cargo-zigbuild
  • Example workflow: Include additional files
  • Other examples
  • Optimize Rust binary
• Supported events
• Security
• Compatibility
• Related Projects
• License

Usage

This action builds and uploads Rust binary that specified by bin option to GitHub Releases.

Currently, this action is basically intended to be used in combination with an action like create-gh-release-action that creates a GitHub release when a tag is pushed. See also supported events.

Inputs

Name	Required	Description	Type	Default
bin	✓	Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list)	String
token		GitHub token for uploading assets to GitHub Releases (see action.yml for more)	String	${{ github.token }}
archive		Archive name (non-extension portion of filename) to be uploaded	String	$bin-$target
target	[1]	Target triple, default is host triple	String	(host triple)
features		Cargo build features to enable (space or comma separated list)	String
no-default-features		Whether to disable cargo build default features	Boolean	false
all-features		Whether to build with --all-features flag	Boolean	false
package		Package names to build (whitespace or comma separated list)	String
workspace		Whether to build with --workspace flag	Boolean	false
locked		Whether to build with --locked flag	Boolean	false
tar		On which platform to distribute the .tar.gz file (all, unix, windows, or none)	String	unix
tar-xz		On which platform to distribute the .tar.xz file (all, unix, windows, or none)	String	none
zip		On which platform to distribute the .zip file (all, unix, windows, or none)	String	windows
checksum		Algorithms to be used for checksum (sha256, sha512, b2, sha1, or md5) (whitespace or comma separated list). Note: b2 is not available by default on macOS, install b2sum to use it. sha1 and md5 are insecure and strongly discouraged.	String
include		Additional files to be included to the archive (whitespace or comma separated list)	String
asset		Additional files to be uploaded separately (whitespace or comma separated list)	String
leading-dir		Whether to create the leading directory in the archive or not	Boolean	false
bin-leading-dir		Create extra leading directory(s) for binary file(s) specified by bin option	String
build-tool		Tool to build binaries (cargo, cross, or cargo-zigbuild, see cross-compilation example for more)	String
ref		Fully-formed tag ref for this release (see action.yml for more)	String
manifest-path		Path to Cargo.toml	String	Cargo.toml
profile		The cargo profile to build. This defaults to the release profile.	String	release
dry-run		Build and compress binaries, but do not upload them (see action.yml for more)	Boolean	false
dry-run-intended		Suppress informational dry-run warnings, keeping the rest	Boolean	false
codesign		Sign build products using codesign on macOS	String
codesign-prefix		Prefix for the codesign identifier on macOS	String
codesign-options		Specifies a set of option flags to be embedded in the code signature on macOS. See the codesign manpage for details.	String

[1] This is optional but it is recommended that this always be set to clarify which target you are building for if macOS is included in the matrix because GitHub Actions changed the default architecture of macos-latest since macos-14.

(Previously, option names were only in "snake_case", but now both "kebab-case" and "snake_case" are available.)

Outputs

Name	Description
archive	Archive base name.
zip	.zip archive file name.
tar	.tar.gz archive file name.
tar-xz	.tar.xz archive file name.
sha256	SHA256 checksum file name.
sha512	SHA512 checksum file name.
b2	BLAKE2 checksum file name.
sha1	SHA1 checksum file name.
md5	MD5 checksum file name.

Example workflow: Basic usage

In this example, when a new tag is pushed, creating a new GitHub Release by using create-gh-release-action, then uploading Rust binary to the created GitHub Release.

An archive file with a name like $bin-$target.tar.gz will be uploaded to GitHub Release.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releaseruns-on: ubuntu-latestpermissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...

You can specify multiple binaries when the root manifest is a virtual manifest or specified binaries are in the same crate.

- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: app1,app2# (optional) Archive name (non-extension portion of filename) to be uploaded.# [default value: $bin-$target]# [possible values: the following variables and any string]# variables:# - $bin - Binary name (non-extension portion of filename).# - $target - Target triple.# - $tag - Tag of this release.# When multiple binary names are specified, default archive name or $bin variable cannot be used.archive: app-$target

Example workflow: Basic usage (multiple platforms)

This action supports Linux, macOS, and Windows as a host OS and supports binaries for various targets.

See also cross-compilation example.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releasestrategy:
matrix:
include:
- target: x86_64-unknown-linux-gnuos: ubuntu-latest
- target: x86_64-apple-darwinos: macos-latest
- target: x86_64-pc-windows-msvcos: windows-latestruns-on: ${{ matrix.os }}permissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Target triple, default is host triple.# This is optional but it is recommended that this always be set to# clarify which target you are building for if macOS is included in# the matrix because GitHub Actions changed the default architecture# of macos-latest since macos-14.target: ${{ matrix.target }}# (optional) On which platform to distribute the `.tar.gz` file.# [default value: unix]# [possible values: all, unix, windows, none]tar: unix# (optional) On which platform to distribute the `.zip` file.# [default value: windows]# [possible values: all, unix, windows, none]zip: windows

Example workflow: Customize archive name

By default, this action will upload an archive file with a name like $bin-$target.$extension.

You can customize archive name by archive option.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releaseruns-on: ubuntu-latestpermissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
bin: ...# (optional) Archive name (non-extension portion of filename) to be uploaded.# [default value: $bin-$target]# [possible values: the following variables and any string]# variables:# - $bin - Binary name (non-extension portion of filename).# - $target - Target triple.# - $tag - Tag of this release.# When multiple binary names are specified, default archive name or $bin variable cannot be used.archive: $bin-$tag-$target

Example workflow: Build with different features on different platforms

This action enables the systemd and io_uring features for Linux, and leave macOS, and Windows with default set of features.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releasestrategy:
matrix:
include:
- target: x86_64-unknown-linux-gnuos: ubuntu-latestfeatures: systemd,io_uring
- target: x86_64-apple-darwinos: macos-latest
- target: x86_64-pc-windows-msvcos: windows-latestruns-on: ${{ matrix.os }}permissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Target triple, default is host triple.target: ${{ matrix.target }}# (optional) On which platform to distribute the `.tar.gz` file.# [default value: unix]# [possible values: all, unix, windows, none]tar: unix# (optional) On which platform to distribute the `.zip` file.# [default value: windows]# [possible values: all, unix, windows, none]zip: windows# (optional) Build with the given set of features if any.features: ${{ matrix.features || '' }}

Example workflow: Cross-compilation

cross

By default, this action uses cross for cross-compilation (if cross supports that target). In the following example, only aarch64-unknown-linux-gnu uses cross, the rest use cargo.

If cross is not installed, this action calls cargo install cross --locked to install cross. If you want to speed up the installation of cross or use an older version of cross, consider using install-action.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releasestrategy:
matrix:
include:
- target: aarch64-unknown-linux-gnuos: ubuntu-latest
- target: aarch64-apple-darwinos: macos-latest
- target: x86_64-unknown-linux-gnuos: ubuntu-latest
- target: x86_64-apple-darwinos: macos-latest# Universal macOS binary is supported as universal-apple-darwin.
- target: universal-apple-darwinos: macos-latestruns-on: ${{ matrix.os }}permissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Target triple, default is host triple.target: ${{ matrix.target }}

setup-cross-toolchain-action

However, if the host has another cross-compilation setup, it will be respected. The following is an example using setup-cross-toolchain-action. In this example, this action uses cargo for all targets.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releasestrategy:
matrix:
include:
- target: aarch64-unknown-linux-gnuos: ubuntu-latest
- target: aarch64-apple-darwinos: macos-latest
- target: x86_64-unknown-linux-gnuos: ubuntu-latest
- target: x86_64-apple-darwinos: macos-latestruns-on: ${{ matrix.os }}permissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- name: Install cross-compilation toolsuses: taiki-e/setup-cross-toolchain-action@v1with:
target: ${{ matrix.target }}runner: none # Skip installation of cross-testing related tools because we only do cross-compilation.if: startsWith(matrix.os, 'ubuntu')
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Target triple, default is host triple.target: ${{ matrix.target }}

cargo-zigbuild

if you want to use cargo-zigbuild, if the heuristic to detect host cross-compilation setups does not work well, or if you want to force the use of cargo or cross, you can use the build-tool input option.

If cargo-zigbuild is not installed, this action calls pip3 install cargo-zigbuild to install cargo-zigbuild.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional)changelog: CHANGELOG.mdupload-assets:
needs: create-releasestrategy:
matrix:
include:
- target: x86_64-unknown-linux-gnuos: ubuntu-latestbuild-tool: cargo-zigbuild# cargo-zigbuild's glibc version suffix is also supported.
- target: aarch64-unknown-linux-gnu.2.17os: ubuntu-latestbuild-tool: cargo-zigbuild
- target: aarch64-apple-darwinos: macos-latestbuild-tool: cargoruns-on: ${{ matrix.os }}permissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required)bin: ...# (optional) Target triple, default is host triple.target: ${{ matrix.target }}# (optional) Tool to build binaries (cargo, cross, or cargo-zigbuild)build-tool: ${{ matrix.build-tool }}

Example workflow: Include additional files

If you want include additional file to the archive, you can use the include option.

name: Releasepermissions:
contents: readon:
push:
tags:
- v[0-9]+.*jobs:
create-release:
runs-on: ubuntu-latestpermissions:
contents: write # for taiki-e/create-gh-release-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/create-gh-release-action@v1with:
# (optional) Path to changelog.changelog: CHANGELOG.mdupload-assets:
needs: create-releaseruns-on: ubuntu-latestpermissions:
contents: write # for taiki-e/upload-rust-binary-actionsteps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Additional files to be included to the archive (whitespace or comma separated list).# Note that glob pattern is not supported yet.include: LICENSE,README.md

By default, the expanded archive does not include the leading directory. In the above example, the directory structure of the archive would be as follows:

/<bin>
/LICENSE
/README.md

You can use the leading-dir option to create the leading directory.

- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Additional files to be included to the archive (whitespace or comma separated list).# Note that glob pattern is not supported yet.include: LICENSE,README.md# (optional) Whether to create the leading directory in the archive or not. default to false.leading-dir: true

In the above example, the directory structure of the archive would be as follows:

/<archive>/
/<archive>/<bin>
/<archive>/LICENSE
/<archive>/README.md

You can use the bin-leading-dir option to create extra leading directory(s) for binary file(s) specified by bin option.

- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Additional files to be included to the archive (whitespace or comma separated list).# Note that glob pattern is not supported yet.include: LICENSE,README.md# (optional) Whether to create the leading directory in the archive or not. default to false.leading-dir: true# (optional) Create extra leading directory(s) for binary file(s) specified by `bin` option. default to empty.bin-leading-dir: opt/leading

In the above example, the directory structure of the archive would be as follows:

/<archive>/
/<archive>/opt/leading/<bin>
/<archive>/LICENSE
/<archive>/README.md

If you want upload additional file separately, you can use the asset option.

upload-assets:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v6
- uses: taiki-e/upload-rust-binary-action@v1with:
# (required) Binary names (non-extension portion of filename) to build and upload (whitespace or comma separated list).# Note that glob pattern is not supported yet.bin: ...# (optional) Additional files to be uploaded separately (whitespace or comma separated list).# Note that glob pattern is not supported yet.asset: LICENSE,README.md

In the above example, the following 3 files will be uploaded:

<bin>-<target>.tar.gz
LICENSE
README.md

Other examples

• cargo-hack
• tokio-console

Optimize Rust binary

You can optimize performance or size of Rust binaries by passing the profile options. The profile options can be specified by [profile] table in Cargo.toml, cargo config, environment variables, etc.

The followings are examples to specify profile options:

• lto

  With profile:

  [profile.release]
  lto = true

  With environment variable:

  env:
  CARGO_PROFILE_RELEASE_LTO: true

• codegen-units

  With profile:

  [profile.release]
  codegen-units = 1

  With environment variable:

  env:
  CARGO_PROFILE_RELEASE_CODEGEN_UNITS: 1

• strip

  With profile:

  [profile.release]
  strip = "symbols"

  Default is strip = debuginfo.

Note: Some of these options may increase the build time.

Supported events

The following two events are supported by default:

• tags (on.push.tags)

  For example:

  on:
  push:
  tags:
  - v[0-9]+.*

• GitHub release (on.release)

  For example:

  on:
  release:
  types: [created]

You can upload binaries from arbitrary event to arbitrary tag by specifying the ref input option.

For example, to upload binaries to the my_tag tag, specify ref input option as follows:

with:
ref: refs/tags/my_tag

Security

The @v<major> tags are updated with each release. If you want to enhance workflow stability and security against supply chain attacks, consider using the @v<major>.<minor>.<patch> tag or their hash to pin the version and regularly updating with dependency cooldown. Since all releases are immutable, pinning the version in either way should have the same effect.

Compatibility

This action has been tested for GitHub-hosted runners (Ubuntu, macOS, Windows).

To use this action in self-hosted runners or in containers, at least the following tools are required:

• rustup, cargo, rustc
• bash
• GNU tar
• gh (GitHub CLI)
• zip (only Unix-like)
• 7z (only Windows)

Note that what this action installs for its setup (such as above tools) is considered an implementation detail if they are installed by this action's side, and there is no guarantee that they will be available in subsequent steps, because this action is not an action for installing those tools.

Related Projects

• create-gh-release-action: GitHub Action for creating GitHub Releases based on changelog.
• setup-cross-toolchain-action: GitHub Action for setup toolchains for cross compilation and cross testing for Rust.
• install-action: GitHub Action for installing development tools.
• cache-cargo-install-action: GitHub Action for cargo install with cache.
• checkout-action: GitHub Action for checking out a repository. (Simplified actions/checkout alternative that does not depend on Node.js.)

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.