Local CI Testing With Act#

⚠️ Configuration Removed: As of PR #90 (GoReleaser v2 migration), the .actrc configuration file has been removed from the dbSurveyor project. This page documents historical configuration and provides guidance for manual act setup. Users wishing to use act for local CI testing must now configure it manually.

Lead Section#

Local CI Testing with Act refers to the development practice of running GitHub Actions workflows locally on a developer's machine using act, an open-source tool that simulates GitHub Actions execution environments. While the dbsurveyor project previously provided a project-level .actrc configuration file, this file was removed as part of a cleanup effort to eliminate configuration files not integrated into CI or the justfile workflow.

The primary goal of local CI testing is to achieve local/CI parity, ensuring that the same validation checks run identically in both local development environments and remote continuous integration pipelines. This approach reduces the feedback loop for developers by catching issues locally that would otherwise only surface after pushing code and waiting for remote CI runners to execute.

Important Note: The dbsurveyor README documentation references several just recipes for act testing (such as setup-act, test-ci-local, test-lint-local, etc.), however these recipes do not currently exist in the justfile. Users must invoke act commands directly rather than through just recipe wrappers.

Act Tool Overview#

What is Act?#

Act is an open-source command-line tool developed by nektos that allows developers to run GitHub Actions workflows locally using Docker containers. It parses GitHub Actions workflow YAML files from the .github/workflows/ directory and executes them in Docker containers that approximate the GitHub-hosted runner environments.

Key Capabilities#

Act provides several core capabilities for local workflow testing:

• Workflow Execution: Run complete workflows or individual jobs from .github/workflows/*.yml files
• Runner Emulation: Simulate GitHub-hosted runners (ubuntu-latest, windows-latest, macos-latest) using Docker images
• Event Triggering: Test different GitHub event triggers (push, pull_request, workflow_dispatch, etc.)
• Secret Management: Inject secrets for local testing through configuration files
• Environment Customization: Configure environment variables, platform mappings, and container settings

Limitations#

While act provides substantial value for local testing, it has inherent limitations compared to actual GitHub Actions execution:

• Platform Differences: All runners execute in Linux Docker containers, even when simulating macOS or Windows
• GitHub Context: Some GitHub-specific contexts and services may not be available or may behave differently
• External Integrations: Features requiring GitHub infrastructure (Pages deployment, SARIF uploads, GitHub API interactions) have limited or no functionality
• Performance: Local execution may differ in timing and resource availability compared to GitHub-hosted runners

DBSurveyor Act Configuration#

Removal and Rationale#

The .actrc configuration file was removed from the dbSurveyor project in PR #90 as part of a cleanup effort that eliminated 15 unused or redundant configuration files. The file was removed because:

• It was not integrated into the CI pipeline or justfile workflow
• The documented just recipes for act testing were never implemented
• Developers who wish to use act can configure it manually per their own needs

Historical Configuration (For Reference)#

Previously, the dbsurveyor project provided a comprehensive .actrc configuration file that customized act's behavior for the project's specific needs:

# Platform mappings using catthehacker images
-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04
-P ubuntu-18.04=ghcr.io/catthehacker/ubuntu:act-18.04
-P macos-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P windows-latest=ghcr.io/catthehacker/ubuntu:act-latest

# Environment variables for Rust development
--env CARGO_TERM_COLOR=never
--env TERM=dumb
--env RUST_LOG=info

# Debugging and compatibility settings
--verbose
--container-architecture linux/amd64
--secret-file .secrets

Platform Mappings#

The historical configuration used catthehacker's act images for runner simulation, which are specifically designed for act and include common development tools. All platform types (ubuntu, macos, windows) mapped to Ubuntu-based containers, as act runs all workflows in Linux Docker containers regardless of the target platform specified in workflow files.

Environment Variables#

The historical configuration set Rust-specific environment variables to ensure consistent behavior during local testing:

• CARGO_TERM_COLOR=never: Disables color output in Cargo to prevent terminal escape sequences in act logs
• TERM=dumb: Indicates a non-interactive terminal environment
• RUST_LOG=info: Sets the default logging level for Rust applications

Apple Silicon Compatibility#

The --container-architecture linux/amd64 flag ensured compatibility on Apple Silicon (ARM64) Macs by forcing containers to use x86_64 architecture, which is emulated through Rosetta 2 or QEMU. This prevented architecture-related issues when running workflows designed for x86_64 GitHub runners.

Manual Configuration for Current Users#

Since the .actrc file no longer exists, developers wishing to use act must provide configuration via command-line flags or create their own local .actrc file (not committed to the repository). To replicate the historical configuration, create a local .actrc file in the project root with the content shown above, or use command-line flags:

# Example: Run act with manual configuration
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest \
    --env CARGO_TERM_COLOR=never \
    --env TERM=dumb \
    --env RUST_LOG=info \
    --container-architecture linux/amd64 \
    --verbose

Available GitHub Actions Workflows#

The dbsurveyor project includes six GitHub Actions workflows that can be tested with act:

1. CI Workflow (ci.yml)#

The main CI workflow provides comprehensive code quality checks and testing:

Jobs:

• quality: Code formatting checks and linting
• tests: Matrix-based testing for different database features (postgresql, sqlite, mysql, mongodb, mssql) and capabilities (encryption, compression)
• coverage: Test coverage reporting with Codecov integration

Triggers: push/pull_request to main, workflow_dispatch

2. Release Workflow (release.yml)#

The release workflow handles building and publishing releases:

Features:

• Cross-compilation for Linux, macOS, and Windows using cargo-zigbuild
• Asset creation and GitHub release publication

Triggers: tags matching v*.*.*

3. Documentation Workflow (docs.yml)#

The documentation workflow builds and deploys project documentation:

Outputs:

• Rustdoc API documentation
• mdBook user documentation with plugins
• GitHub Pages deployment

Triggers: push/pull_request to main, workflow_dispatch

4. Security Workflow (security.yml)#

The security workflow performs security audits:

Checks:

• cargo deny for dependency license and security checks
• cargo outdated for dependency updates

Triggers: CI completion, daily schedule (6:00 UTC), workflow_dispatch

5. Scorecard Workflow (scorecard.yml)#

The OSSF Scorecard workflow analyzes supply-chain security:

Analysis:

• OSSF Scorecard security metrics
• Code scanning results upload

Triggers: branch protection changes, weekly schedule (Mondays 14:25 UTC), push to main, workflow_dispatch

Note: This workflow has limited functionality with act due to GitHub-specific features (SARIF uploads, security scanning integration).

6. Copilot Setup Workflow (copilot-setup-steps.yml)#

The Copilot setup workflow validates development environment setup:

Validation:

• Mise-based development environment setup
• just info command execution

Triggers: workflow_dispatch, push/pull_request affecting the workflow file

Usage Examples#

Basic Act Usage#

Since the .actrc file no longer exists and the documented just recipes were never implemented, developers must invoke act commands directly with manual configuration:

# Run the entire CI workflow with manual platform mapping
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest -j quality -j tests

# Run a specific job from the CI workflow
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest -j quality

# Run workflows triggered by push events
act push -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

# List all workflows
act -l

# Dry run to see what would execute
act -n

Testing Specific Workflows#

# Test the CI workflow with a specific event
act workflow_dispatch -W .github/workflows/ci.yml \
    -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

# Test security checks
act workflow_dispatch -W .github/workflows/security.yml \
    -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

# Test documentation build (may fail on GitHub Pages deployment)
act workflow_dispatch -W .github/workflows/docs.yml \
    -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

Advanced Options#

# Run with specific environment variables and platform mapping
act -j tests -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest \
    --env RUST_BACKTRACE=1

# Use a specific Docker platform
act -j quality -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest \
    --container-architecture linux/amd64

# Reuse containers for faster iteration
act -j tests -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest --reuse

# Interactive debugging with shell access
act -j tests -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest --bind

Simplified Configuration Approach#

To avoid specifying platform mappings and flags for every command, create a local .actrc file in your project directory (do not commit this to the repository):

# Create a local .actrc file
cat > .actrc <<EOF
-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04
--env CARGO_TERM_COLOR=never
--env TERM=dumb
--env RUST_LOG=info
--verbose
--container-architecture linux/amd64
EOF

# Now act commands use your local configuration automatically
act -j quality

Local/CI Parity#

CI Check Recipe#

The ci-check just recipe provides local/CI parity by running the same checks that execute in GitHub Actions:

# Run the same checks as CI
just ci-check

According to the README, this command runs format checking, linting (clippy), testing, documentation builds, and cargo-deny security checks.

Differences from Act Testing#

The just ci-check recipe differs from act-based testing:

• Direct Execution: Runs tools directly on the host machine without Docker containerization
• Partial Coverage: Executes core quality checks but not the full matrix of CI jobs
• Fast Feedback: Provides quicker results without Docker overhead
• Environment Sensitive: May produce different results based on local tool versions and system configuration

Complementary Approaches#

Both approaches serve complementary purposes:

• just ci-check: Fast, frequent validation during development
• act: High-fidelity simulation of complete CI pipeline before pushing

Known Limitations and Workarounds#

Configuration File Removal#

The .actrc configuration file no longer exists in the repository as of PR #90. Developers wishing to use act must either:

1. Create their own local .actrc file (not committed to version control)
2. Provide all configuration via command-line flags
3. Set up act configuration in their user's home directory (~/.actrc)

Documentation-Implementation Mismatch#

The documented just recipes (setup-act, test-ci-local, test-lint-local, etc.) do not exist in the justfile. Developers must use act commands directly.

GitHub-Specific Features#

Certain workflow features have limited functionality with act:

• GitHub Pages Deployment: Requires GitHub infrastructure, will fail locally
• Codecov Uploads: Requires valid CODECOV_TOKEN, may be skipped in local testing
• SARIF/Security Scanning: GitHub Code Scanning integration not available locally
• GitHub API Operations: Limited or no functionality without GitHub context

Workaround: Add conditional logic to workflows to skip these steps when running locally:

- name: Upload to GitHub Pages
  if: github.event_name != 'workflow_dispatch' && github.actor != 'nektos/act'
  uses: actions/deploy-pages@v4

Matrix Strategy Testing#

The CI workflow uses matrix strategies to test multiple database features. Testing all matrix combinations locally can be time-consuming and resource-intensive.

Workaround: Test specific matrix combinations:

# Act doesn't directly support matrix filtering, but you can run specific jobs
act -j tests --matrix features:postgresql

Container Performance#

Running workflows in Docker containers on Apple Silicon Macs using x86_64 emulation can be significantly slower than native execution.

Workaround: Use just ci-check for rapid iteration and reserve act testing for final pre-push validation.

Best Practices#

Development Workflow#

1. Rapid Iteration: Use just ci-check for quick validation during development
2. Pre-Push Validation: Run act to test full workflows before pushing
3. Selective Testing: Test specific workflows relevant to your changes
4. Secret Management: Keep .secrets file secure and never commit it

Maintenance#

1. Keep Act Updated: Regularly update act to get the latest features and bug fixes
2. Monitor Docker Images: Update platform image mappings in your local .actrc when new versions are available
3. Sync Configuration: Ensure your local configuration stays aligned with workflow requirements
4. Document Workarounds: Note any workflow-specific limitations or required manual steps

Debugging#

1. Verbose Output: Add --verbose flag for detailed logging
2. Container Reuse: Use --reuse flag for faster iteration when debugging
3. Interactive Access: Use --bind flag to get shell access to containers
4. Incremental Testing: Test individual jobs before running complete workflows

Relevant Code Files#

Related Topics#

• GitHub Actions: The cloud-based CI/CD platform that act emulates locally
• Justfile Automation: Build automation tool used in dbsurveyor for development workflows
• Continuous Integration: Software development practice of frequently integrating code changes
• Docker Containers: Technology used by act to simulate GitHub Actions runner environments
• Development Environment Setup: Related configuration for mise, Rust toolchain, and development tools
• CI/CD Pipeline Design: Principles and patterns for designing effective continuous integration workflows