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
```bash
# 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

3. **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**
   - **Not applicable**: Current workflow uses only shell commands
   - **No external actions**: Maximum compatibility with any Forgejo runner

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

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