GitHub Actions Workflows

This repository includes several GitHub Actions workflows for building, testing, and publishing Docker images.

Workflows

1. Docker Build and Test (docker-test.yml)

• Triggers: Push to main/develop branches, Pull Requests to main
• Purpose: Build and test Docker image without publishing
• Features:
  • Builds Docker image with load: true to make it available for testing
  • Runs health checks
  • Tests API endpoints
  • Tests timezone functionality
  • Security scanning with Trivy (non-blocking)

2. Docker Hub Publishing (docker-build.yml)

• Triggers: Push to main/develop branches, Tags starting with v
• Purpose: Build and publish to Docker Hub
• Features:
  • Multi-platform builds (AMD64, ARM64)
  • Automatic tagging based on branch/tag
  • Security scanning
  • Staging and production deployment hooks

3. GitHub Container Registry (docker-publish-ghcr.yml)

• Triggers: Push to main branch, Tags starting with v
• Purpose: Build and publish to GitHub Container Registry
• Features:
  • Multi-platform builds
  • Automatic tagging
  • Security scanning
  • Uses GitHub token for authentication

4. Security Scan (security-scan.yml)

• Triggers: Weekly schedule, Manual dispatch
• Purpose: Comprehensive security scanning
• Features:
  • Vulnerability scanning with Trivy
  • Results uploaded to GitHub Security tab
  • Non-blocking (won't fail the workflow)

Setup Instructions

For Docker Hub Publishing

Note: Your GitHub username and Docker Hub username can be different. The workflows are configured to use andystevko as the Docker Hub username.

1. Create Docker Hub Account: Sign up at hub.docker.com

2. Create Access Token:

   • Go to Docker Hub → Account Settings → Security
   • Create a new access token
   • Copy the token

3. Add Secrets to GitHub Repository:

   • Go to your GitHub repository → Settings → Secrets and variables → Actions
   • Add the following secrets:
     • DOCKER_USERNAME: andystevko (your Docker Hub username)
     • DOCKER_TOKEN: Your Docker Hub access token

For GitHub Container Registry

No additional setup required! The workflow uses the built-in GITHUB_TOKEN.

Image Tags

The workflows automatically create tags based on:

• Branch pushes: main, develop
• Pull requests: pr-123
• Tags: v1.0.0, v1.0, v1, latest (for main branch)

Security Features

• Trivy Security Scanning: Scans for vulnerabilities
• Multi-platform builds: Supports AMD64 and ARM64
• Cache optimization: Uses GitHub Actions cache for faster builds
• Permission controls: Minimal required permissions

Usage Examples

Pulling Images

Docker Hub:

docker pull andystevko/htmx-fastapi-service:latest
docker pull andystevko/htmx-fastapi-service:v1.0.0

GitHub Container Registry:

docker pull ghcr.io/astevko/htmx-fastapi-service:latest
docker pull ghcr.io/astevko/htmx-fastapi-service:v1.0.0

Running Images

# Run with default settings (Docker Hub)
docker run -p 8000:8000 andystevko/htmx-fastapi-service:latest

# Run with default settings (GitHub Container Registry)
docker run -p 8000:8000 ghcr.io/astevko/htmx-fastapi-service:latest

# Run with environment variables
docker run -p 8000:8000 -e PYTHONPATH=/app andystevko/htmx-fastapi-service:latest

Troubleshooting

Common Issues

1. Build Failures: Check the Actions logs for specific error messages
2. Authentication Errors: Verify Docker Hub credentials are correct
3. Permission Errors: Ensure repository has proper permissions for packages

Security Scanning Issues

If you see "Resource not accessible by integration" errors with SARIF uploads:

1. Enable Code Scanning: Go to repository Settings → Security → Code scanning → Set up code scanning
2. Check Permissions: Ensure the workflow has security-events: write permission
3. Alternative: Use the dedicated security-scan.yml workflow for comprehensive scanning

The security scanning is set to continue-on-error: true so it won't block your Docker builds.

Docker Image Testing Issues

If you see "pull access denied" or "repository does not exist" errors in the test workflow:

1. Image Availability: The workflow uses load: true to make the built image available for testing
2. Step Context: Each step runs in the same runner, so the image persists between steps
3. Cache: Uses GitHub Actions cache for faster builds

This ensures the Docker image built in one step is available for testing in subsequent steps.

Manual Testing

You can test the Docker image locally:

# Build the image
docker build -t htmx-fastapi-service .

# Run the container
docker run -p 8000:8000 htmx-fastapi-service

# Test the endpoints
curl http://localhost:8000/
curl http://localhost:8000/api/messages

Contributing

When contributing to this repository:

1. Create a feature branch
2. Make your changes
3. Create a pull request
4. The workflows will automatically test your changes
5. Once merged, images will be automatically built and published