sexy.pivoine.art/.github/workflows/README.md

GitHub Actions Workflows

This directory contains automated workflows for building, scanning, and managing Docker images for sexy.pivoine.art.

Workflows

1. Build and Push Docker Image (docker-build-push.yml)

Triggers:

• Push to main or develop branches
• New version tags (e.g., v1.0.0)
• Pull requests to main
• Manual trigger via workflow_dispatch

What it does:

• Builds multi-platform Docker images (AMD64 + ARM64)
• Pushes to GitHub Container Registry as ghcr.io/valknarxxx/sexy
• Creates tags based on branch, version, and commit SHA
• Uses build cache for faster builds
• Only builds (doesn't push) for PRs

Image Tags:

• latest - Latest build from main branch
• main, develop - Branch-based tags
• v1.0.0, v1.0, v1 - Semantic version tags
• main-abc123 - Branch + commit SHA
• pr-123 - Pull request builds
• Custom tags via manual trigger

Usage:

# Automatically triggered on push to main
git push origin main

# Create a release tag
git tag v1.0.0
git push origin v1.0.0

# Manual trigger from GitHub UI
# Actions → Build and Push Docker Image → Run workflow

Pulling images:

# Latest version
docker pull ghcr.io/valknarxxx/sexy:latest

# Specific version
docker pull ghcr.io/valknarxxx/sexy:v1.0.0

# Specific branch
docker pull ghcr.io/valknarxxx/sexy:develop

2. Docker Image Security Scan (docker-scan.yml)

Triggers:

• Daily at 2 AM UTC (scheduled)
• Push to main branch
• New version tags
• Manual trigger

What it does:

• Scans the latest image for vulnerabilities using Trivy
• Reports CRITICAL and HIGH severity issues
• Uploads results to GitHub Security tab
• Runs on a schedule to detect new vulnerabilities

Viewing results:

• Go to repository → Security → Code scanning alerts
• Check workflow run summary for table output

Manual scan:

# From GitHub UI
# Actions → Docker Image Security Scan → Run workflow

3. Cleanup Old Docker Images (cleanup-images.yml)

Triggers:

• Weekly on Sunday at 3 AM UTC
• Manual trigger

What it does:

• Removes old untagged image versions
• Keeps the 10 most recent versions by default
• Frees up GitHub Container Registry storage

Manual cleanup:

# From GitHub UI with custom retention
# Actions → Cleanup Old Docker Images → Run workflow
# Set "keep_count" parameter (default: 10)

Setup Requirements

1. Enable GitHub Container Registry

The workflows automatically use GitHub's Container Registry (ghcr.io). No additional setup needed - the GITHUB_TOKEN is automatically provided to workflows.

2. Repository Settings

Ensure the following permissions are enabled:

1. Settings → Actions → General

   • Allow GitHub Actions: ✅ Enabled
   • Workflow permissions: "Read and write permissions"

2. Settings → Packages

   • Package visibility will inherit from repository visibility
   • Can be changed to public/private as needed

3. Branch Protection (Optional)

For production use, consider:

1. Settings → Branches → Branch protection rules
   • Protect main branch
   • Require PR reviews
   • Require status checks (Docker build) to pass

Secrets and Environment Variables

Required Secrets

None! The workflows use the built-in GITHUB_TOKEN which is automatically provided.

Optional Secrets

If you need to deploy to production automatically, you can add:

• PRODUCTION_SSH_KEY - For SSH deployment
• PRODUCTION_HOST - Production server hostname
• PRODUCTION_USER - Production server user

Image Visibility

By default, GitHub Container Registry packages inherit repository visibility:

• Public repository → Public images
• Private repository → Private images

To change package visibility:

1. Go to https://github.com/users/valknarxxx/packages/container/sexy/settings
2. Change visibility under "Danger Zone"

Pulling Images

Public Images

docker pull ghcr.io/valknarxxx/sexy:latest

Private Images

# 1. Create a GitHub Personal Access Token with read:packages scope
#    Settings → Developer settings → Personal access tokens → Tokens (classic)
#    Scopes: read:packages

# 2. Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# 3. Pull the image
docker pull ghcr.io/valknarxxx/sexy:latest

Best Practices

Version Tagging

Use semantic versioning for releases:

# Major release (breaking changes)
git tag v2.0.0

# Minor release (new features)
git tag v1.1.0

# Patch release (bug fixes)
git tag v1.0.1

# Always push tags
git push origin --tags

Development Workflow

# 1. Create feature branch
git checkout -b feature/new-feature

# 2. Make changes and commit
git add .
git commit -m "Add new feature"

# 3. Push and create PR
git push origin feature/new-feature
# Create PR on GitHub - this triggers a test build

# 4. Merge to develop for staging
# Merging to develop triggers a build with 'develop' tag

# 5. Merge to main for production
# Merging to main triggers a build with 'latest' tag

# 6. Tag releases
git checkout main
git pull
git tag v1.0.0
git push origin v1.0.0
# This triggers a build with version tags

Monitoring

Build Status

Check workflow status:

• Repository → Actions → Select workflow
• View logs, artifacts, and summaries

Image Registry

View published images:

• https://github.com/valknarxxx?tab=packages
• Or repository → Packages

Security Alerts

View vulnerability scans:

• Repository → Security → Code scanning alerts
• Filter by "Trivy" tool

Troubleshooting

Build Failures

Problem: Build fails at Rust installation

Solution:

• Check GitHub Actions runner status
• Verify Dockerfile Rust installation steps
• Check build logs for network issues

Problem: Permission denied when pushing

Solution:

• Verify repository Settings → Actions → General → Workflow permissions
• Ensure "Read and write permissions" is enabled

Problem: Multi-platform build timeout

Solution:

• Builds can take 30-45 minutes for multi-platform
• This is normal for Rust/WASM compilation
• Consider splitting platforms or using self-hosted runners

Pull Failures

Problem: Cannot pull private image

Solution:

# Ensure you're logged in
echo $GITHUB_TOKEN | docker login ghcr.io -u valknarxxx --password-stdin

# Verify token has read:packages scope

Problem: Image not found

Solution:

• Check image exists: https://github.com/valknarxxx?tab=packages
• Verify tag name is correct
• Ensure you have access to private packages

Advanced Configuration

Self-Hosted Runners

For faster builds, use self-hosted runners:

jobs:
  build-and-push:
    runs-on: self-hosted  # Change from ubuntu-latest
    # ... rest of job

Build-time Variables

Pass build arguments:

build-args: |
  NODE_ENV=production
  CUSTOM_VAR=value

Deploy on Push

Add a deployment job:

jobs:
  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to production
        # Add deployment steps

Cost Optimization

Storage Limits

GitHub provides:

• Public repos: Unlimited storage and bandwidth
• Private repos: 500MB storage, 1GB bandwidth (free tier)

Optimization Tips

1. Regular cleanup: Run cleanup workflow weekly
2. Limit platforms: Build only needed architectures
3. Use cache: BuildKit cache reduces rebuild time
4. Minimize layers: Optimize Dockerfile

Monitoring Usage

Check package storage:

• Settings → Billing → Packages
• View storage usage per package