app/scripts/README.md

Development Scripts

test-ci-locally.sh

Tests the Gitea Actions workflow locally using act (nektos/act) in Docker.

Purpose

When CI tests fail, this script allows you to run the exact same workflow (.gitea/workflows/magnitude.yml) locally to debug issues without repeatedly pushing to trigger CI runs. It uses nektos/act to execute the workflow in a containerized environment, just like GitHub Actions or Gitea Actions would.

Usage

./scripts/test-ci-locally.sh

What it does

1. Loads environment variables from .env file
2. Runs nektos/act:latest Docker container with:
   • Docker socket mounted (so act can create containers)
   • Current directory mounted as workspace
   • Secrets passed from .env file
3. Executes .gitea/workflows/magnitude.yml using act
4. The workflow then runs its steps:
   • Checkout code
   • Create .env file with secrets
   • Run tests with docker-compose (starts SurrealDB, Next.js, Magnitude)
   • Show logs on failure
   • Upload test results
   • Cleanup

Requirements

• Docker installed and running
• .env file with test credentials and secrets
• Docker socket accessible at /var/run/docker.sock

How It Works

The script uses nektos/act to execute the workflow YAML file. Act is compatible with both GitHub Actions and Gitea Actions workflows. It creates containers according to the workflow definition, which in turn uses docker-compose.ci.yml to set up the test environment:

act (nektos/act Docker container)
  ↓ executes .gitea/workflows/magnitude.yml
  ↓ which runs docker-compose with:
magnitude (Playwright container)
  ↓ depends on (waits for health check)
nextjs (Node.js container running pnpm dev)
  ↓ depends on (waits for health check)
surrealdb (SurrealDB container)

Note on nektos/act vs gitea/act_runner

• nektos/act is designed for local workflow testing and is compatible with both GitHub Actions and Gitea Actions
• gitea/act_runner is a runner daemon that needs to connect to a Gitea instance and is not designed for offline local testing
• This script uses nektos/act which provides the local testing experience similar to running workflows in CI

Debugging CI Failures

If Gitea Actions fail:

1. Check the workflow logs for errors in Gitea UI
2. Run ./scripts/test-ci-locally.sh to execute the workflow locally
3. The script will show the same steps and output as CI
4. Fix issues based on the local test results
5. Run script again to verify fix
6. Commit and push once tests pass locally

This is much faster than debugging via CI push cycles and gives you the exact same environment!