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
• Container: Ruby 3.3 Alpine with Node.js
• Features:
  • Runs RSpec tests with full GitHub Actions support
  • 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
• Container: Ruby 3.3 Alpine with Node.js
• Features:
  • Runs unit and integration tests separately
  • Generates coverage reports
  • Uploads test artifacts

3. node-ruby.yml - Node.js + Ruby Workflow

• Triggers: Push to main, tags, and pull requests
• Jobs: Test → Build → Notify
• Container: Node.js 18 Alpine with Ruby
• Features:
  • Uses Node.js base image with Ruby installed
  • Full GitHub Actions compatibility
  • Optimized for actions requiring Node.js

4. simple.yml - Simple Shell-Based Workflow

• Triggers: Push to main, tags, and pull requests
• Jobs: Test → Build → Notify
• Container: Ruby 3.3 Alpine
• Features:
  • Uses basic shell commands instead of complex actions
  • Manual git cloning and Docker operations
  • Minimal dependencies

5. minimal.yml - Minimal Test-Only Workflow

• Triggers: Push events
• Jobs: Test → Build
• Container: Ruby 3.3 Alpine
• Features:
  • Extremely minimal setup
  • Basic test execution
  • No external action dependencies

6. shell-only.yml - Pure Shell-Based Workflow

• Triggers: Push to main, tags, and pull requests
• Jobs: Test → Build → Notify
• Container: Ruby 3.3 Alpine (with auto-detection)
• Features:
  • No GitHub Actions dependencies at all
  • Auto-detects package manager (apk, apt-get, yum, dnf)
  • Manual git cloning and Docker operations
  • Most compatible with any Forgejo runner setup

7. 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

8. 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. Package manager not found / Node.js executable not found error

   /var/run/act/workflow/0: line 2: apk: command not found
   OCI runtime exec failed: exec failed: unable to start container process: 
   exec: "node": executable file not found in $PATH: unknown
   

   Solutions:

   • Recommended: Use shell-only.yml (pure shell, no actions, most compatible with any runner)
   • Fixed in main workflows: ci.yml, test.yml, build.yml, and docker.yml now auto-detect package manager
   • Alternative: Use node-ruby.yml (Node.js base image with Ruby)
   • Alternative: Use simple.yml or minimal.yml (shell-based, limited actions)
   • Check your Forgejo runner configuration and container image support

2. Working directory not found error

   OCI runtime exec failed: exec failed: unable to start container process: 
   chdir to cwd ("/workspace/james/baktainer/./app") set in config.json failed: 
   no such file or directory: unknown
   

   Solutions:

   • Fixed: All workflows now use explicit cd app commands instead of working-directory defaults
   • The error occurred because working-directory was set before repository checkout
   • Repository must be cloned/checked out before changing to subdirectories

3. Actions not running

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

4. Docker build failures

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

5. Test failures

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

6. GitHub Actions compatibility

   • Some actions require Node.js runtime
   • Use node-ruby.yml for full GitHub Actions support
   • Use simple.yml for shell-based alternatives

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.