tschunkorder/.forgejo/README.md

Forgejo CI/CD Workflows

This directory contains CI/CD workflows for the TschunkOrder project using Forgejo Actions.

Available Workflows

1. ci.yml - Full CI Pipeline

A comprehensive CI pipeline that runs:

• Backend Tests: Runs pytest on the backend code
• Backend Build: Tests backend imports and startup
• Frontend Build: Type checking, linting, and build process
• Docker Build: Tests all Docker builds including docker-compose

2. ci-simple.yml - Simplified CI Pipeline

A streamlined workflow that combines all tests and builds into a single job:

• Backend tests and import verification
• Frontend type checking, linting, and build
• Docker build verification

Setup Instructions

1. Enable Forgejo Actions

Ensure that Forgejo Actions are enabled in your repository settings.

2. Configure Runners

Set up Forgejo runners with the docker label. The workflows require runners that have declared the docker label.

3. Required Software on Runners

Your runners should have:

• Python 3.11+
• Node.js 18+
• Docker (for Docker build tests)
• Git

4. Workflow Triggers

The workflows are triggered on:

• Push to master or develop branches
• Pull requests to master or develop branches

Workflow Details

Backend Testing

• Installs Python dependencies from backend/requirements.txt
• Runs pytest with verbose output
• Tests backend module imports
• Verifies backend startup (with timeout)

Frontend Testing

• Installs Node.js dependencies
• Runs TypeScript type checking
• Runs ESLint for code quality
• Builds the production bundle
• Verifies build output exists

Docker Testing

• Builds backend Docker image
• Builds frontend Docker image
• Tests docker-compose build
• All builds are tagged for testing purposes

Customization

Adding New Tests

To add new test steps:

1. Backend Tests: Add new pytest files in the backend/ directory
2. Frontend Tests: Add new npm scripts in frontend/package.json
3. Docker Tests: Add new Dockerfile tests in the workflow

Modifying Triggers

Edit the on section in the workflow files to change when workflows run:

on:
  push:
    branches: [ master, develop, feature/* ]
  pull_request:
    branches: [ master ]
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

Environment Variables

Add environment variables if needed:

env:
  PYTHONPATH: ./backend
  NODE_ENV: production

Runner Selection

The workflows currently use runs-on: docker. You can modify this to use different runner labels:

jobs:
  my-job:
    runs-on: ubuntu-latest  # or any other label

Troubleshooting

Common Issues

1. Python Import Errors: Ensure all dependencies are in requirements.txt
2. Node.js Build Failures: Check that all dependencies are in package.json
3. Docker Build Failures: Verify Dockerfiles are valid and dependencies are available
4. Runner Not Available: Ensure you have runners with the docker label online

Debugging

• Check workflow logs in the Forgejo Actions tab
• Use echo statements in workflow steps for debugging
• Test workflows locally using act (GitHub Actions local runner)

Security Notes

• Workflows run in isolated environments
• No secrets are exposed in logs
• Docker builds use temporary tags for testing
• All builds are cleaned up after testing