CI/CD

Cortexa uses GitHub Actions for automated cross-platform builds and release publishing. Every tagged commit triggers a parallel build across four platform targets, producing installers that are uploaded as GitHub Release assets.

Workflow Overview

The release workflow lives at .github/workflows/release.yml and triggers on version tags:

on:
  push:
    tags:
      - 'v*'

When you push a tag like v0.8.3, the workflow runs four parallel jobs, one per platform target.

Build Matrix

Platform	Runner	Rust Target	Output
Windows x64	windows-latest	(default, x86_64-pc-windows-msvc)	_x64-setup.exe, .msi
Windows ARM64	windows-11-arm	aarch64-pc-windows-msvc	_arm64-setup.exe
macOS Apple Silicon	macos-latest	aarch64-apple-darwin	_aarch64.dmg
macOS Intel	macos-latest	x86_64-apple-darwin	_x64.dmg

The strategy uses fail-fast: false so a failure on one platform does not cancel the other builds.

Workflow Steps

Each matrix job runs these steps:

1. Checkout

- uses: actions/checkout@v4

2. Install Rust

- name: Install Rust
  uses: dtolnay/rust-toolchain@stable
  with:
    targets: aarch64-apple-darwin,x86_64-apple-darwin,aarch64-pc-windows-msvc

Installs the stable Rust toolchain with cross-compilation targets for all platforms. Each runner only uses the target it needs, but specifying all targets in the toolchain step simplifies the matrix.

3. Install Node.js

- name: Install Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 22

4. Install Frontend Dependencies

- name: Install frontend dependencies
  run: npm ci

Uses npm ci (clean install) for reproducible builds from package-lock.json.

5. Build and Release

- name: Build and release
  uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tagName: ${{ github.ref_name }}
    releaseName: 'Cortexa ${{ github.ref_name }}'
    releaseBody: |
      See the assets below to download the installer for your platform.

      **Windows (x64)**: `_x64-setup.exe` or `.msi`
      **Windows (ARM64)**: `_arm64-setup.exe`
      **macOS (Apple Silicon)**: `_aarch64.dmg`
      **macOS (Intel)**: `_x64.dmg`
    releaseDraft: false
    prerelease: false
    args: ${{ matrix.args }}

The tauri-apps/tauri-action handles:

• Running npm run tauri build with the appropriate target.
• Creating a GitHub Release (or updating an existing one for the same tag).
• Uploading the built installer as a release asset.
• The args field passes the --target flag for cross-compilation (e.g., --target aarch64-pc-windows-msvc). Windows x64 uses no args (it builds for the default host target).

Creating a Release

Step-by-step

1. Update the version in both files:

   • src-tauri/tauri.conf.json: the "version" field
   • src-tauri/Cargo.toml: the version field

2. Commit the version bump:

   git add src-tauri/tauri.conf.json src-tauri/Cargo.toml
   git commit -m "v0.8.3"

3. Create and push the tag:

   git tag v0.8.3
   git push origin main
   git push origin v0.8.3

4. Monitor the build on the GitHub Actions tab. Four jobs will run in parallel.

5. Verify the release at https://github.com/<owner>/cortexa/releases/tag/v0.8.3. It should have four installer assets.

Tag Naming

Tags must start with v to match the workflow trigger (v*). Examples: v0.8.3, v1.0.0, v1.0.0-beta.1.

Release Assets

After all four jobs complete, the GitHub Release contains:

Asset	Platform	Size (approx.)
Cortexa_0.8.3_x64-setup.exe	Windows x64	~15 MB
Cortexa_0.8.3_x64_en-US.msi	Windows x64 (MSI)	~15 MB
Cortexa_0.8.3_arm64-setup.exe	Windows ARM64	~15 MB
Cortexa_0.8.3_aarch64.dmg	macOS Apple Silicon	~12 MB
Cortexa_0.8.3_x64.dmg	macOS Intel	~12 MB

Users download the appropriate installer for their platform from the Releases page.

Permissions

The workflow requires contents: write permission to create releases and upload assets:

permissions:
  contents: write

This is granted via the GITHUB_TOKEN secret, which is automatically available in GitHub Actions.

Build Times

Phase	Approximate Time
Checkout + setup	30 seconds
npm ci	30-60 seconds
Rust compilation (first build)	10-15 minutes
Rust compilation (cached)	3-5 minutes
Tauri bundling	1-2 minutes
Asset upload	30 seconds

First builds on a fresh runner take the longest because there is no Rust compilation cache. Subsequent builds benefit from GitHub Actions' built-in caching when available.

Customization

Adding Linux Targets

To add Linux builds, extend the matrix:

matrix:
  include:
    # ... existing entries ...
    - platform: ubuntu-22.04
      args: ''

Linux requires additional system dependencies installed in a setup step:

- name: Install Linux dependencies
  if: runner.os == 'Linux'
  run: |
    sudo apt update
    sudo apt install -y libwebkit2gtk-4.1-dev libsoup-3.0-dev librsvg2-dev

Caching Rust Builds

Add a cache step to speed up repeated builds:

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

Code Signing

For production releases without SmartScreen/Gatekeeper warnings:

Windows (Authenticode):

• Set certificateThumbprint in tauri.conf.json under bundle.windows.
• Add the certificate to the GitHub Actions runner as a secret.
• Tauri handles signing during the bundling step.

macOS (Notarization):

• Set up a Developer ID certificate.
• Configure notarization credentials as GitHub secrets.
• Add Tauri's macOS signing configuration.

Neither is currently configured. See the Desktop deployment page for details.

Troubleshooting CI

Build fails on one platform only

Check the job logs for that specific matrix entry. Common causes:

• Windows ARM64: The windows-11-arm runner may have different pre-installed tools.
• macOS: Ensure Xcode command-line tools are available (they are on macos-latest).
• Missing Rust target: The dtolnay/rust-toolchain step should install all targets.

Release not created

• Verify the tag starts with v.
• Check that the GITHUB_TOKEN has contents: write permission.
• Look for "release already exists" errors if you retagged the same version.

Assets missing from release

If some platform builds fail but others succeed, the release is created with partial assets. Fix the failing build and either:

• Delete the tag and release, then re-push.
• Or manually upload the missing asset after a local build.