home / skills / dchuk / claude-code-tauri-skills / tauri-pipeline-github

tauri-pipeline-github skill

needs review

This skill guides you to configure GitHub Actions pipelines for building, testing, and releasing Tauri desktop apps across platforms.

npx playbooks add skill dchuk/claude-code-tauri-skills --skill tauri-pipeline-github

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

9.9 KB

---
name: building-tauri-with-github-actions
description: Guides users through setting up Tauri GitHub Actions CI/CD pipelines and workflows for automated building, testing, and releasing cross-platform desktop applications.
---

# Building Tauri Apps with GitHub Actions

This skill covers CI/CD pipeline configuration for Tauri applications using GitHub Actions and the official `tauri-apps/tauri-action`.

## Overview

GitHub Actions enables automated building, testing, and releasing of Tauri applications across Windows, macOS, and Linux platforms. The `tauri-action` handles the complexity of cross-platform builds and release management.

## Workflow Triggers

### Push to Release Branch

```yaml
name: 'publish'
on:
  workflow_dispatch:
  push:
    branches:
      - release
```

### Tag-Based Releases

```yaml
name: 'publish'
on:
  push:
    tags:
      - 'app-v*'
```

## Platform Matrix Configuration

### Standard Multi-Platform Matrix

```yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
```

### With ARM Linux Support (Public Repos Only)

Add `ubuntu-22.04-arm` to the matrix for native ARM64 Linux builds (public repositories only).

## Complete Workflow Example

```yaml
name: 'publish'

on:
  workflow_dispatch:
  push:
    branches:
      - release

jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build and release
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseBody: 'See the assets to download this version and install.'
          releaseDraft: true
          prerelease: false
          args: ${{ matrix.args }}
```

## Package Manager Variants

### pnpm

```yaml
- name: Setup pnpm
  uses: pnpm/action-setup@v4
  with:
    version: latest

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'pnpm'

- name: Install frontend dependencies
  run: pnpm install
```

### Yarn

```yaml
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'yarn'

- name: Install frontend dependencies
  run: yarn install --frozen-lockfile
```

## Caching Strategies

### Rust Artifact Caching

```yaml
- name: Rust cache
  uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'
```

### Node.js Dependency Caching

Configure via the `cache` parameter in `actions/setup-node@v4`: `'npm'`, `'yarn'`, or `'pnpm'`.

## Linux Dependencies

Ubuntu requires WebKit and related libraries:

```yaml
- name: Install dependencies (Ubuntu only)
  if: matrix.platform == 'ubuntu-22.04'
  run: |
    sudo apt-get update
    sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
```

## Release Automation

### tauri-action Configuration

```yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'
    releaseBody: 'See the assets to download this version and install.'
    releaseDraft: true
    prerelease: false
    args: ${{ matrix.args }}
```

### Version Placeholders

The action automatically replaces `__VERSION__` with the app version from `tauri.conf.json`.

### Release Options

| Option | Description |
|--------|-------------|
| `tagName` | Git tag for the release (supports `__VERSION__` placeholder) |
| `releaseName` | Display name for the release |
| `releaseBody` | Release notes content |
| `releaseDraft` | Create as draft release (`true`/`false`) |
| `prerelease` | Mark as prerelease (`true`/`false`) |

## Artifact Uploads

### Upload Build Artifacts Without Release

```yaml
- name: Build Tauri app
  uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  id: tauri

- name: Upload artifacts
  uses: actions/upload-artifact@v4
  with:
    name: tauri-build-${{ matrix.platform }}
    path: src-tauri/target/release/bundle/
```

## GitHub Token Configuration

The `GITHUB_TOKEN` requires write permissions for release creation.

### Repository Settings

1. Go to Settings > Actions > General
2. Under "Workflow permissions"
3. Select "Read and write permissions"
4. Save

### Workflow Permissions

```yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
```

## Non-Root Project Configuration

For projects where Tauri is not at the repository root:

```yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    projectPath: './apps/desktop'
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'
```

## ARM Build Emulation (Alternative)

For ARM builds in private repositories or when native ARM runners are unavailable:

```yaml
jobs:
  build-arm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build ARM64
        uses: pguyot/[email protected]
        with:
          base_image: dietpi:rpi_armv8_bullseye
          commands: |
            apt-get update
            apt-get install -y curl build-essential libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
            source $HOME/.cargo/env
            curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
            apt-get install -y nodejs
            npm ci
            npm run tauri build
```

Note: ARM emulation builds take approximately one hour for fresh projects.

## Code Signing Integration

### macOS Signing Environment Variables

```yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
    APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
```

### Windows Signing Environment Variables

```yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
    TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
```

## CI-Only Workflow (No Release)

For pull request validation without creating releases:

```yaml
name: 'CI Build'

on:
  pull_request:
    branches:
      - main

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build Tauri app
        run: npm run tauri build -- ${{ matrix.args }}
```

## Troubleshooting

### Permission Denied for Release Creation

Ensure workflow has write permissions and verify repository settings allow Actions to create releases:

```yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
```

### Linux Build Failures

Verify all dependencies are installed with the Ubuntu dependency installation step.

### macOS Target Not Found

Ensure Rust targets are installed for cross-compilation:

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: 'aarch64-apple-darwin,x86_64-apple-darwin'
```

### Cache Not Working

Verify the workspace path matches your project structure:

```yaml
- uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'
```

Overview

This skill guides you through setting up GitHub Actions CI/CD pipelines for Tauri v2 desktop apps so you can automate building, testing, and releasing cross-platform binaries. It explains matrix configurations, required dependencies, caching, release automation with tauri-action, and platform-specific signing steps. The content focuses on practical workflow examples and common troubleshooting tips.

How this skill works

You define GitHub Actions workflows that run across a platform matrix (macOS, Linux, Windows) and use tauri-apps/tauri-action to build and optionally publish releases. The workflows install platform dependencies, set up Node.js and Rust toolchains, cache build artifacts and dependencies, then run the Tauri build and either upload artifacts or create GitHub releases. Environment variables and secrets control signing and release behavior.

When to use it

Automating cross-platform builds for each commit, tag, or manual dispatch.
Publishing installers and binaries as GitHub releases from a release branch or tags.
Validating pull requests with CI-only Tauri builds to catch build regressions.
Adding code signing for macOS and Windows release artifacts.
Building ARM Linux targets natively (public repos) or via emulation for private repos.

Best practices

Use a matrix strategy to run platform-specific builds in parallel and set fail-fast: false.
Cache Rust and Node artifacts (swatinem/rust-cache and setup-node cache) to speed builds.
Keep sensitive credentials in GitHub Secrets and grant GITHUB_TOKEN write permissions in repository settings.
Install Ubuntu WebKit and related packages in Linux jobs to prevent build failures.
Use projectPath when Tauri is not at the repository root to target the correct directory.
Prefer native ARM runners for ARM64 builds when possible; use emulation as a fallback for private repos.

Example use cases

Create a publish workflow triggered by pushes to a release branch that builds and drafts releases across macOS, Linux, and Windows.
Run CI-only matrix builds on pull requests to ensure cross-platform compatibility before merging.
Produce platform-specific installers and upload them as artifacts without creating a release.
Automatically replace version placeholders (__VERSION__) from tauri.conf.json when tagging releases.
Integrate macOS and Windows code signing by injecting certificate secrets into the workflow environment.

FAQ

Do I need special permissions to create releases from a workflow?

Yes. Set workflow permissions to allow contents: write and enable read/write workflow permissions in the repository Actions settings so GITHUB_TOKEN can create releases.

How do I build ARM64 Linux artifacts for private repositories?

Private repos lack public ARM runners; use an emulation action (e.g., pguyot/arm-runner-action) to run an ARM64 chroot or container, but expect significantly longer build times.