awesome-app/.github/workflows/README.md

GitHub Actions Workflows

This directory contains automated workflows for building, testing, and deploying the awesome-app.

Workflows

1. db.yml - Build Awesome Database

Triggers:

• Schedule: Every 6 hours
• Manual: workflow_dispatch
• Push to main (when db.yml or build-db.js changes)

Purpose: Builds the SQLite database by scraping awesome lists from GitHub.

Artifacts:

• awesome.db - SQLite database file
• db-metadata.json - Metadata about the build (timestamp, hash, counts)

Retention: 90 days

---

2. docker-publish.yml - Build and Push Docker Image

Triggers:

• Push to main or develop branches
• Git tags matching v*.*.*
• Pull requests to main
• Manual: workflow_dispatch

Dependencies:

• Calls db.yml workflow first
• Downloads database artifact before building Docker image

Features:

• Multi-platform builds (linux/amd64, linux/arm64)
• Automatic semantic versioning from git tags
• GitHub Container Registry (ghcr.io)
• Build cache optimization
• Database metadata embedded in image labels
• Configurable database inclusion via INCLUDE_DATABASE build arg (default: true in CI)

Image Tags:

• latest - Latest build from main branch
• main - Latest main branch build
• develop - Latest develop branch build
• v1.2.3 - Semantic version tags
• main-abc1234 - Branch + commit SHA

Image Labels:

• Standard OCI labels (title, description, vendor, source)
• Database metadata (timestamp, hash, counts)

---

3. docker-scan.yml - Security Scanning

Triggers:

• Schedule: Daily at 2 AM UTC
• Push to main branch
• Git tags matching v*.*.*
• Manual: workflow_dispatch

Purpose: Scans Docker images for security vulnerabilities using Trivy.

Features:

• SARIF report upload to GitHub Security tab
• Scans for CRITICAL, HIGH, and MEDIUM severity issues
• Automated daily security checks

---

4. cleanup-images.yml - Cleanup Old Docker Images

Triggers:

• Schedule: Weekly on Sundays at 3 AM UTC
• Manual: workflow_dispatch (configurable retention count)

Purpose: Removes old untagged Docker images to save storage.

Configuration:

• Default: Keep 10 most recent versions
• Configurable via workflow_dispatch input

---

Workflow Integration

The workflows are designed to work together:

graph LR
    A[db.yml] --> B[docker-publish.yml]
    B --> C[docker-scan.yml]
    D[cleanup-images.yml]

1. Database Build (db.yml) runs every 6 hours and on-demand
2. Docker Build (docker-publish.yml) depends on database build
3. Security Scan (docker-scan.yml) runs after image push
4. Cleanup (cleanup-images.yml) runs weekly to free storage

Usage

Manual Database Build

gh workflow run db.yml

Manual Docker Build

gh workflow run docker-publish.yml -f tag=custom-tag

Manual Security Scan

gh workflow run docker-scan.yml

Manual Cleanup

gh workflow run cleanup-images.yml -f keep_count=20

Environment Variables

Required repository secrets:

• GITHUB_TOKEN - Automatically provided
• WEBHOOK_URL - (Optional) Webhook for database updates
• WEBHOOK_SECRET - (Optional) Secret for webhook authentication

Docker Image

Pull the latest image:

docker pull ghcr.io/valknarness/awesome-app:latest

Run with embedded database (CI builds):

docker run -p 3000:3000 ghcr.io/valknarness/awesome-app:latest

Run with volume-mounted database (local builds):

docker run -p 3000:3000 -v $(pwd)/data:/app/data ghcr.io/valknarness/awesome-app:latest

Build Arguments

Control database inclusion when building locally:

# Include database in image (like CI)
docker build --build-arg INCLUDE_DATABASE=true -t awesome-app .

# Exclude database (mount at runtime)
docker build --build-arg INCLUDE_DATABASE=false -t awesome-app .

Or with docker-compose:

services:
  awesome-app:
    build:
      args:
        INCLUDE_DATABASE: true  # or false

Best Practices

1. Database builds happen automatically every 6 hours
2. Docker images are built on every push to main/develop
3. Security scans run daily to catch new vulnerabilities
4. Old images are cleaned up weekly to save storage
5. Database metadata is embedded in Docker image labels for traceability