baktainer/.forgejo/README.md
James Paterni e294b9b1a3
Some checks failed
Build Docker Image / build (push) Failing after 31s
Minimal CI / test (push) Failing after 10s
Node+Ruby CI Pipeline / build (push) Blocked by required conditions
Node+Ruby CI Pipeline / notify (push) Blocked by required conditions
CI Pipeline / test (push) Failing after 36s
Build and Push Docker Image / test (push) Failing after 12s
Build Docker Image / notify (push) Failing after 1s
CI Pipeline / build (push) Has been skipped
Build and Push Docker Image / build (push) Has been skipped
Simple CI Pipeline / build (push) Has been skipped
CI Pipeline / notify (push) Successful in 1s
Simple CI Pipeline / notify (push) Successful in 1s
Simple CI Pipeline / test (push) Failing after 1s
Run Tests / test (push) Failing after 12s
Minimal CI / build (push) Has been skipped
Node+Ruby CI Pipeline / test (push) Has been cancelled
Fix Node.js executable error in Forgejo Actions workflows
- Install Node.js before checkout in all workflows that use actions
- Updated ci.yml, test.yml, build.yml, and docker.yml
- Updated README.md with fix information
- Resolves "exec: node: executable file not found in $PATH" error

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-15 11:25:02 -04:00

232 lines
No EOL
7.3 KiB
Markdown

# 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. `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
### 7. `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. **Node.js executable not found error**
```
OCI runtime exec failed: exec failed: unable to start container process:
exec: "node": executable file not found in $PATH: unknown
```
**Solutions**:
- **Fixed in main workflows**: `ci.yml`, `test.yml`, `build.yml`, and `docker.yml` now install Node.js before checkout
- Alternative: Use `node-ruby.yml` (Node.js base image with Ruby)
- Alternative: Use `simple.yml` or `minimal.yml` (shell-based, no Node.js actions)
- Manual fix: Add Node.js to Ruby Alpine: `apk add --no-cache nodejs npm`
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.