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        # Complete CI/CD pipeline
└── README.md         # This file

Workflow

ci.yml - Complete CI/CD Pipeline

• Triggers:
  • Push to main branch → Test + Build + Deploy
  • Version tags (v*..) → Test + Build + Deploy with version tag
  • Pull requests → Test only
• Jobs: Test → Build → Notify
• Container: Ruby 3.3 Alpine (with auto-detection)
• Features:
  • Test Job: Installs dependencies, runs RSpec tests
  • Build Job: Builds Docker image, pushes to Docker Hub as :latest and :version (for tags)
  • Notify Job: Reports pipeline status
  • Pure Shell Commands: No GitHub Actions dependencies for maximum compatibility
  • Auto-Detection: Supports multiple package managers (apk, apt-get, yum, dnf)
  • Robust: Manual git cloning and Docker operations work with any Forgejo runner

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 (/{owner}/{repository}/settings → Repository → Secrets):

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

Important: All three secrets must be configured for the workflow to succeed. Missing secrets will cause the build to fail with clear error messages.

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 progress format
• Automatic dependency installation with package manager detection

Building

• Docker builds from Alpine Ruby base
• Automatic tagging with :latest and version tags (:v1.2.3)
• Docker Hub integration with secure authentication
• Build status reporting

Compatibility

• Pure shell commands for maximum Forgejo runner compatibility
• Package manager auto-detection (apk, apt-get, yum, dnf)
• No external action dependencies

Usage Examples

Manual Workflow Trigger

# Push to main (triggers full CI/CD: test → build → deploy)
git push origin main

# Create and push version tag (triggers test → build → deploy with version tag)
git tag v0.1.1
git push origin v0.1.1

# Create pull request (triggers test only)
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:

   • Current workflow uses pure shell commands - no GitHub Actions dependencies
   • Auto-detects package manager (apk, apt-get, yum, dnf) for maximum compatibility
   • If still experiencing issues: Check your Forgejo runner configuration and container image support

2. Docker push reference format error

   Error parsing reference: ":latest" is not a valid repository/tag: invalid reference format
   

   Solutions:

   • Missing secret: Configure DOCKER_IMAGE_NAME secret in repository settings
   • Example value: jamez001/baktainer (your Docker Hub username/repository)
   • Path: Go to /{owner}/{repository}/settings → Repository → Secrets
   • Verify: All three Docker secrets must be configured (USERNAME, PASSWORD, IMAGE_NAME)

3. 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: Workflow uses explicit cd app commands instead of working-directory defaults
   • The error occurred because working-directory was set before repository checkout
   • Repository must be cloned before changing to subdirectories

4. Actions not running

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

5. Docker build failures

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

6. Test failures

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

7. GitHub Actions compatibility

   • Not applicable: Current workflow uses only shell commands
   • No external actions: Maximum compatibility with any Forgejo runner

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

This workflow is designed to be compatible with the existing GitHub Actions in .github/workflows/. Key adaptations made:

1. Pure shell commands: No external action dependencies for maximum compatibility
2. Runner specification: Uses docker with Ruby 3.3 Alpine container
3. Package manager detection: Auto-detects apk, apt-get, yum, or dnf
4. Manual operations: Git clone and Docker commands work with any runner setup

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

Simplified Design

This single workflow replaces multiple complex workflows with one simple, reliable pipeline that:

• Tests your Ruby application with RSpec
• Builds a Docker image
• Deploys by pushing to Docker Hub with proper tagging
• Works with any Forgejo runner configuration