baktainer/.forgejo/README.md

Forgejo Actions Configuration

This directory contains Forgejo Actions workflows for the Baktainer project. Forgejo Actions provides Continuous Integration similar to GitHub Actions but runs on Forgejo instances.

Directory Structure

.forgejo/
├── workflows/
│   ├── ci.yml        # Main CI pipeline (test + build)
│   ├── test.yml      # Test-only workflow
│   ├── build.yml     # Build-only workflow
│   └── docker.yml    # Advanced Docker workflow
└── README.md         # This file

Workflows

1. ci.yml - Main CI Pipeline

• Triggers: Push to main, tags, and pull requests
• Jobs: Test → Build → Notify
• Features:
  • Runs RSpec tests in Ruby 3.3 Alpine container
  • Builds and pushes Docker images to Docker Hub
  • Provides status notifications

2. test.yml - Test-Only Workflow

• Triggers: Push to main and pull requests
• Jobs: Test
• Features:
  • Runs unit and integration tests separately
  • Generates coverage reports
  • Uploads test artifacts

3. build.yml - Build-Only Workflow

• Triggers: Push to main and tags
• Jobs: Build → Notify
• Features:
  • Builds Docker images after tests pass
  • Supports versioned tags
  • Provides build status notifications

4. docker.yml - Advanced Docker Workflow

• Triggers: Push to main and tags
• Jobs: Test → Build
• Features:
  • Uses Docker Buildx for advanced builds
  • Implements Docker layer caching
  • Automatic metadata extraction

Key Differences from GitHub Actions

1. Directory Location

• GitHub: .github/workflows/
• Forgejo: .forgejo/workflows/

2. Runner Types

• Uses runs-on: docker for containerized jobs
• Can specify custom container images with container:

3. Action Compatibility

• Most GitHub Actions work with Forgejo Actions
• Actions are sourced from configured action repositories
• Uses same syntax for actions/checkout@v4, docker/build-push-action@v5, etc.

4. Environment Variables

• Same ${{ github.* }} variables available
• Same secret management with ${{ secrets.* }}

Required Secrets

Configure these secrets in your Forgejo repository settings:

Secret	Description	Example
DOCKER_USERNAME	Docker Hub username	jamez001
DOCKER_PASSWORD	Docker Hub password or token	dckr_pat_...
DOCKER_IMAGE_NAME	Docker image name	jamez001/baktainer

Configuration Requirements

1. Enable Repository Actions

1. Go to /{owner}/{repository}/settings
2. Click on "Repository" tab
3. Check "Enable Repository Actions"

2. Forgejo Runner Setup

• Forgejo Actions requires a separate Forgejo Runner
• Runner must be configured by the Forgejo administrator
• Runner supports Docker, LXC, or host-based execution

3. Action Repository Configuration

• Actions are sourced from configured repositories
• Default actions available at https://data.forgejo.org
• Administrator can configure custom action sources

Workflow Features

Testing

• Ruby 3.3 with Alpine Linux
• RSpec test suite with JUnit XML output
• Coverage reporting with simplecov
• Artifact upload for test results

Building

• Multi-stage Docker builds from Alpine Ruby base
• Automatic tagging with version tags
• Docker Hub integration with secure authentication
• Build notifications with status reporting

Caching

• Ruby gem caching for faster builds
• Docker layer caching (in advanced workflow)
• Dependency caching between runs

Usage Examples

Manual Workflow Trigger

# Push to main (triggers ci.yml)
git push origin main

# Create and push version tag (triggers build)
git tag v0.1.1
git push origin v0.1.1

# Create pull request (triggers test.yml)
git push origin feature-branch
# Then create PR in Forgejo UI

Monitoring Workflow Status

1. Navigate to repository in Forgejo
2. Click on "Actions" tab
3. View workflow runs and logs
4. Check artifact downloads

Troubleshooting

Common Issues

1. Actions not running

   • Check if Repository Actions are enabled
   • Verify Forgejo Runner is installed and running
   • Check workflow file syntax

2. Docker build failures

   • Verify Docker Hub credentials in secrets
   • Check Dockerfile syntax
   • Ensure runner has Docker access

3. Test failures

   • Check Ruby version compatibility
   • Verify system dependencies in Alpine
   • Review test output in workflow logs

Debugging Steps

1. Check workflow syntax:

   # Validate YAML syntax
   yamllint .forgejo/workflows/ci.yml
   

2. Test locally:

   # Run tests in similar environment
   docker run --rm -v $(pwd):/app -w /app ruby:3.3-alpine sh -c \
     "apk add --no-cache build-base libffi-dev linux-headers postgresql-dev git && \
      cd app && bundle install && bundle exec rspec"
   

3. Check logs:

   • View detailed logs in Forgejo Actions UI
   • Check runner logs on server
   • Verify secret configuration

Migration from GitHub Actions

The workflows in this directory are designed to be compatible with the existing GitHub Actions in .github/workflows/. Key adaptations made:

1. Runner specification: Changed from ubuntu-latest to docker with container specification
2. Dependency installation: Added explicit Alpine package installation
3. Simplified caching: Adapted caching strategy for Forgejo environment
4. Container-based execution: Optimized for Docker container runtime

Both GitHub Actions and Forgejo Actions can coexist in the same repository, allowing for gradual migration or dual CI/CD setup.