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
```bash
# 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. **Actions not running**
   - Check if Repository Actions are enabled
   - Verify Forgejo Runner is installed and running
   - Check workflow file syntax

3. **Docker build failures**
   - Verify Docker Hub credentials in secrets
   - Check Dockerfile syntax
   - Ensure runner has Docker access

4. **Test failures**
   - Check Ruby version compatibility
   - Verify system dependencies in Alpine
   - Review test output in workflow logs

5. **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**:
   ```bash
   # Validate YAML syntax
   yamllint .forgejo/workflows/ci.yml
   ```

2. **Test locally**:
   ```bash
   # 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.