The Apps Image repository uses act to run GitHub Actions workflows locally. This allows you to test version checking and image building before pushing changes.
Prerequisites Install act on your system:
# Using curl curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash # Or download from releases # https://github.com/nektos/act/releases
# Using chocolatey choco install act-cli # Or using scoop scoop install act
Testing Version Checking The check-version.yaml workflow validates version tracking configuration and checks for updates.
Check Single Application Test version checking for a specific application:
act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/icones
This will:
Read the application’s meta.json
Check the configured repository for version updates
Display current and available versions
Show whether an update is needed
Check Multiple Applications Test several applications at once:
act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/icones,apps/rayso,base/nginx
Separate multiple contexts with commas (no spaces).
Check All Applications Run version checks across the entire repository:
act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=all
Checking all applications may take several minutes depending on the number of apps and API rate limits.
Check Base Images Test base image version tracking:
act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=base/nginx
Testing Image Builds The build-test.yaml workflow allows you to test Docker image building locally.
View Docker metadata without actually building the image:
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/icones \ --input build= false \ --input notify= false
This shows:
Docker image names
Tags that will be generated
Platforms that will be built
Build arguments and placeholders
Dry runs are fast and don’t require Docker. Use them to validate configuration before building.
Full Build Test Build the Docker image locally:
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/icones
This will:
Run pre-build scripts (if any)
Build the Docker image
Tag the image locally
Show build logs and results
By default, build=true and notify=false when using the test workflow.
Test Specific Variants Build only specific variants:
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=base/nginx \ --input build= false \ --input notify= false \ --input variants=latest,vue
Omit the variants input to test all variants.
Real-World Testing Examples Test New Application When adding a new application, test it thoroughly:
Check version tracking works
act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/your-app
Verify it detects the correct version from the upstream repository.
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/your-app \ --input build= false \ --input notify= false
Check that tags and platforms are correct.
If you have a pre.sh script:
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/your-app \ --input notify= false
Watch the pre.sh script execution and verify it completes successfully.
After successful build, test the image:
docker run -p 3000:3000 aliuq/your-app:latest Test Multi-Variant Configuration For applications with multiple variants (like cobalt or nginx):
Test All Variants
Test Specific Variant
Test Production + Dev
act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=base/nginx \ --input build= false \ --input notify= false
Test Version Tracking Types Different version tracking strategies:
Package.json Version
Git Commit SHA
Git Tags
Manual
# Test version tracking from package.json act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/weektodo
Should show the version from package.json in the repository. # Test SHA tracking act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/icones
Should show the latest commit SHA from the repository. # Test tag tracking act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=base/vscode
Should show the latest Git tag from the repository. # Manual versioning (no automatic checks) act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=base/alpine
Should indicate that manual versioning is configured. Input Required Default Description debugNo falseEnable debug output contextYes - Application path(s) or “all”
Input Required Default Description debugNo falseEnable debug output contextYes - Application path (e.g., “apps/icones”) buildNo trueActually build the image notifyNo falseSend notifications variantsNo (all) Comma-separated variant names
Understanding Output Version Check Output ✓ Checking apps/icones Current version: 0bc5918 Latest version: 0bc5918 Status: Up to date
or
✓ Checking apps/weektodo Current version: 2.2.0 Latest version: 2.3.0 Status: Update available
Build Output ✓ Running pre-build script: pre.sh + VERSION=73fac26 + mkdir -p app + cd app ... ✓ Building Docker image Image: aliuq/rayso Tags: latest, 73fac26 Platforms: linux/amd64, linux/arm64 ... ✓ Build successful
Debugging Build Failures Pre-build Script Failures If the pre.sh script fails:
Check the script output for the specific error
Verify version placeholders are correct
Test the script manually:
cd apps/your-app bash -x pre.sh
The -x flag shows each command as it executes.
Docker Build Failures If the Docker build fails:
Check Dockerfile syntax
Verify version ARG is correct:
Test the Dockerfile directly:
docker build -t test --build-arg VERSION= 1.0.0 apps/your-app
Version Detection Failures If version checking fails:
Verify the repository URL is correct
Check the file path for version tracking:
{ "checkver" : { "type" : "version" , "repo" : "https://github.com/owner/repo" , "file" : "package.json" // Verify this exists } }
For monorepos, specify the path:
{ "checkver" : { "type" : "version" , "repo" : "https://github.com/owner/repo" , "file" : "web/package.json" , // Subdirectory path "path" : "web" // For SHA tracking } }
Common Testing Workflows Before Committing Always test before pushing changes:
# 1. Check version tracking act workflow_dispatch -W .github/workflows/check-version.yaml \ --input debug= true \ --input context=apps/your-app # 2. Validate Docker metadata act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/your-app \ --input build= false \ --input notify= false # 3. Test full build act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/your-app # 4. Test the image docker run -p 3000:3000 aliuq/your-app:latest
Testing Configuration Changes When updating meta.json:
# Test metadata generation act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/your-app \ --input build= false \ --input notify= false
Review the output to verify:
Image names are correct
Tags are generated as expected
Platforms are appropriate
Placeholders are replaced properly
Testing Base Image Updates When updating a base image:
# 1. Build the base image act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=base/nginx # 2. Test an app that uses it act workflow_dispatch -W .github/workflows/build-test.yaml \ --input debug= true \ --input context=apps/icones
Use Dry Runs First Always validate metadata before building:
# Fast: 1-2 seconds act workflow_dispatch -W .github/workflows/build-test.yaml \ --input context=apps/icones \ --input build= false \ --input notify= false # Slow: 5-30 minutes act workflow_dispatch -W .github/workflows/build-test.yaml \ --input context=apps/icones
Test Specific Variants Don’t build all variants if you only changed one:
# Only test the dev variant act workflow_dispatch -W .github/workflows/build-test.yaml \ --input context=apps/cobalt \ --input variants=dev
Use Docker BuildKit Enable BuildKit for faster builds:
Or add to your shell configuration:
echo 'export DOCKER_BUILDKIT=1' >> ~/.bashrc
BuildKit provides better caching, parallel builds, and more efficient layer management.
Troubleshooting act Not Found If act command is not found:
# Check if installed which act # Install if missing (macOS) brew install act # Verify installation act --version
Docker Daemon Not Running If you get Docker connection errors:
# Start Docker Desktop (macOS/Windows) # Or start Docker daemon (Linux) sudo systemctl start docker
Workflow Not Found If act can’t find the workflow:
# Make sure you're in the repository root pwd # List available workflows ls .github/workflows/ # Use absolute path if needed act workflow_dispatch -W $PWD /.github/workflows/check-version.yaml
Permission Denied If you get permission errors:
# Add user to docker group (Linux) sudo usermod -aG docker $USER # Log out and back in for changes to take effect
Next Steps