GitHub Workflows

Diagnose, fix, and optimize GitHub Actions workflows for Rust projects.

Purpose

Set up robust CI/CD pipelines for Rust projects with proper caching, testing, linting, and release automation.

Before Making Changes: Verify Current State

ALWAYS start by checking the current workflow configuration before making any changes:

1. Get Repository Information

bash

# Get current repo info (owner, name)
gh repo view --json nameWithOwner,owner,name

# Example output: {"name":"rust-self-learning-memory","nameWithOwner":"d-o-hub/rust-self-learning-memory","owner":"d-o-hub"}

2. List Existing Workflows

bash

# List all workflows
gh workflow list

# View workflow details
gh workflow view <workflow-name>

3. Check Recent Workflow Runs

bash

# List recent runs
gh run list --limit 10

# View specific run details
gh run view <run-id>

# View run logs
gh run view <run-id> --log

4. Check Existing Workflow Files

bash

# List workflow files
ls -la .github/workflows/

# Review each workflow
cat .github/workflows/*.yml

5. Check for Existing Issues

bash

# Check for workflow-related issues
gh issue list --label ci --label github-actions --label workflow

Only after understanding the current state should you suggest changes or additions.

Quick Reference

Caching Strategies - Manual cache, rust-cache, sccache, cache keys
Troubleshooting - Common issues, debugging, fixes
Advanced Features - Coverage, security, benchmarking, quality gates, docs deployment
Release Management - Automated releases, versioning, changelog generation, crates.io publishing

Complete Rust CI Workflow (2025)

yaml

name: Rust CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1

jobs:
  check:
    name: Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Cache Rust dependencies
        uses: Swatinem/rust-cache@v2

      - name: Run cargo check
        run: cargo check --all --verbose

  fmt:
    name: Format
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt

      - name: Check formatting
        run: cargo fmt -- --check

  clippy:
    name: Clippy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy

      - name: Cache Rust dependencies
        uses: Swatinem/rust-cache@v2

      - name: Run clippy
        run: cargo clippy --all-targets --all-features -- -D warnings

  test:
    name: Test
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        rust: [stable]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ matrix.rust }}

      - name: Cache Rust dependencies
        uses: Swatinem/rust-cache@v2

      - name: Run tests
        run: cargo test --all --verbose

      - name: Run tests with all features
        run: cargo test --all-features --verbose

  coverage:
    name: Coverage
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install cargo-llvm-cov
        run: cargo install cargo-llvm-cov

      - name: Generate coverage
        run: cargo llvm-cov --lcov --all-features --workspace --output-path lcov.info

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          file: ./lcov.info
          fail_ci_if_error: false

Quick Start Workflows

Minimal CI (Quick Feedback)

yaml

name: Quick CI

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - run: cargo check --all
      - run: cargo fmt -- --check
      - run: cargo clippy -- -D warnings
      - run: cargo test --all

Project-Specific: Self-Learning Memory CI

yaml

name: Self-Learning Memory CI

on:
  push:
    branches: [main]
  pull_request:

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - run: cargo check --all --verbose

  fmt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt
      - run: cargo fmt -- --check

  clippy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy
      - uses: Swatinem/rust-cache@v2
      - run: cargo clippy --all-targets -- -D warnings

  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - run: cargo test --all --verbose
      - run: cargo test --all --all-features --verbose

Common Tasks

Setup Rust Toolchain

yaml

# Stable
- uses: dtolnay/rust-toolchain@stable

# With components
- uses: dtolnay/rust-toolchain@stable
  with:
    components: rustfmt, clippy

# Specific version
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: 1.75.0

Cache Dependencies

yaml

# Recommended: Use rust-cache (automatic)
- uses: Swatinem/rust-cache@v2
  with:
    shared-key: "stable"
    save-if: ${{ github.ref == 'refs/heads/main' }}

# Alternative: Manual cache
- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry/index
      ~/.cargo/registry/cache
      target
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      ${{ runner.os }}-cargo-
    save-always: true

See caching-strategies.md for detailed caching options.

Run Tests

yaml

# All tests
- run: cargo test --all

# With verbose output
- run: cargo test --all --verbose

# With all features
- run: cargo test --all-features

# With backtrace
- run: RUST_BACKTRACE=1 cargo test --all

# Single-threaded (for race conditions)
- run: cargo test --all -- --test-threads=1

Build Project

yaml

# Development build
- run: cargo build --all

# Release build
- run: cargo build --release --all

# With timing info
- run: cargo build --release --timings

Lint and Format

Using cargo-llvm-cov (Recommended)

yaml

- name: Install llvm-cov
  run: cargo install cargo-llvm-cov

- name: Generate coverage
  run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info

- name: Upload to Codecov
  uses: codecov/codecov-action@v4
  with:
    files: lcov.info
    token: ${{ secrets.CODECOV_TOKEN }}

Alternative: Generate multiple formats

yaml

- name: Install llvm-cov
  run: cargo install cargo-llvm-cov

- name: Generate coverage (HTML + LCOV)
  run: |
    cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
    cargo llvm-cov --all-features --workspace --html --output-dir coverage

# Run clippy with fix
- run: cargo clippy --fix

Best Practices (2025)

DO:

✓ Use actions/cache@v4 with save-always: true ✓ Use hashFiles('**/Cargo.lock') for cache keys ✓ Implement restore-keys for cache fallback ✓ Use dtolnay/rust-toolchain (not deprecated actions-rs) ✓ Split large caches to avoid 2GB limit ✓ Test on multiple platforms (matrix) ✓ Use Swatinem/rust-cache@v2 for simplicity ✓ Cache both registry and target directory ✓ Set CARGO_TERM_COLOR: always for readable logs ✓ Use continue-on-error for experimental builds

DON'T:

✗ Use deprecated actions-rs/* actions ✗ Create monolithic cache entries >2GB ✗ Cache without restore-keys ✗ Forget save-always: true for partial builds ✗ Cache target/ across different jobs without unique keys ✗ Run expensive operations on every PR ✗ Use actions/cache@v3 and @v4 inconsistently ✗ Hardcode Rust version (use rust-toolchain file)

Common Issues

Quick reference - see troubleshooting.md for full details:

Cache not saved on failure → Use save-always: true
Cache key mismatch → Use hashFiles() and restore-keys
Deprecated actions-rs → Use dtolnay/rust-toolchain
tar creation errors → Use rust-cache or exclude problematic paths
Files >2GB → Split into smaller caches
Workflow permissions → Set permissions: in workflow
Flaky tests → Add retries with nick-fields/retry@v2

Detailed Documentation

Caching Strategies - All caching methods, cache keys, performance tips
Troubleshooting - Issues, fixes, debugging, monitoring
Advanced Features - Releases, coverage, security, multi-platform

Integration with Project

Before suggesting workflow changes:

Run gh repo view --json nameWithOwner,owner,name to get actual repo info
Use the actual owner/repo names in all workflow examples
Check existing workflows with gh workflow list
Review current workflow files in .github/workflows/

For this project (d-o-hub/rust-self-learning-memory):

The workflows ensure all memory-core, memory-storage-turso, and memory-storage-redb crates are tested across platforms
Quality gates enforce 90% code coverage threshold
Benchmarks track performance regressions
Supply chain security with cargo-deny and cargo-audit

Quick Checklist

Before committing workflow changes:

Uses actions/cache@v4 or Swatinem/rust-cache@v2
Has save-always: true for caches
Uses dtolnay/rust-toolchain (not actions-rs)
Caches are <2GB each
Has restore-keys for fallback
Tests on multiple platforms (if needed)
Clippy runs with -D warnings
Format check included
Permissions set appropriately

Search AI Tools

github-workflows

Install this agent skill to your Project

SKILL.md

GitHub Workflows

Purpose

Before Making Changes: Verify Current State

1. Get Repository Information

2. List Existing Workflows

3. Check Recent Workflow Runs

4. Check Existing Workflow Files

5. Check for Existing Issues

Quick Reference

Complete Rust CI Workflow (2025)

Quick Start Workflows

Minimal CI (Quick Feedback)

Project-Specific: Self-Learning Memory CI

Common Tasks

Setup Rust Toolchain

Cache Dependencies

Run Tests

Build Project

Lint and Format

Using cargo-llvm-cov (Recommended)

Alternative: Generate multiple formats

Best Practices (2025)

DO:

DON'T:

Common Issues

Detailed Documentation

Integration with Project

Quick Checklist