ci-templates/README.md

# Cloonar CI Templates

Shared CI/CD templates for Cloonar projects.

## Contents

```
.forgejo/workflows/
  # TYPO3-specific workflows
  typo3-build.yaml            # Build PHP/Node artifacts
  typo3-e2e-test.yaml         # Run Playwright E2E tests
  typo3-staged-deploy.yaml    # Convenience wrapper (all-in-one)

  # Generic Deployer workflows
  deployer-release-create.yaml  # Upload release without switching
  deployer-release-switch.yaml  # Activate a previously uploaded release

deployer/
  typo3-recipe.php            # Shared Deployer configuration

examples/
  project-workflow-staged.yaml  # Composable pattern (recommended)
  project-workflow-simple.yaml  # Wrapper pattern
  project-deploy.php            # Example project deploy.php
  project-servers.yaml          # Example servers.yaml
```

## Quick Start

### 1. Update your project's `build/deploy.php`

Replace your entire deploy.php with:

```php
<?php
namespace Deployer;

// Import shared recipe
require 'https://git.cloonar.com/infrastructure/ci-templates/raw/branch/main/deployer/typo3-recipe.php';

import(__DIR__ . '/servers.yaml');

host('stage')->set('cachetool', '/var/run/phpfpm/myproject.cloonar.dev.sock');
host('production')->set('cachetool', '/var/run/phpfpm/myproject.at.sock');
```

### 2. Keep your `build/servers.yaml` (project-specific)

```yaml
hosts:
  stage:
    hostname: web-arm.cloonar.com
    remote_user: myproject_cloonar_dev
    deploy_path: ~/
    # ... rest of config
```

### 3. Choose your workflow pattern

#### Option A: Composable Pattern (Recommended)

Full control and visibility. Each job appears separately in the pipeline UI.

```yaml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    uses: infrastructure/ci-templates/.forgejo/workflows/typo3-build.yaml@main
    with:
      php_version: '8.3'
      build_frontend: true

  create-stage:
    needs: build
    uses: infrastructure/ci-templates/.forgejo/workflows/deployer-release-create.yaml@main
    with:
      server: stage
    secrets:
      ssh_key: ${{ secrets.STAGE_KEY }}

  switch-stage:
    needs: create-stage
    uses: infrastructure/ci-templates/.forgejo/workflows/deployer-release-switch.yaml@main
    with:
      server: stage
    secrets:
      ssh_key: ${{ secrets.STAGE_KEY }}

  test:
    needs: switch-stage
    uses: infrastructure/ci-templates/.forgejo/workflows/typo3-e2e-test.yaml@main
    with:
      test_url: https://myproject.cloonar.dev

  create-production:
    needs: test
    uses: infrastructure/ci-templates/.forgejo/workflows/deployer-release-create.yaml@main
    with:
      server: production
    secrets:
      ssh_key: ${{ secrets.PROD_KEY }}

  switch-production:
    needs: create-production
    uses: infrastructure/ci-templates/.forgejo/workflows/deployer-release-switch.yaml@main
    with:
      server: production
    secrets:
      ssh_key: ${{ secrets.PROD_KEY }}
```

#### Option B: Wrapper Pattern (Simple)

All-in-one convenience workflow. Less visible but simpler to set up.

```yaml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: infrastructure/ci-templates/.forgejo/workflows/typo3-staged-deploy.yaml@main
    with:
      stage_url: https://myproject.cloonar.dev
      php_version: '8.3'
      run_e2e_tests: true
    secrets:
      stage_key: ${{ secrets.STAGE_KEY }}
      prod_key: ${{ secrets.PROD_KEY }}
```

## Workflow Reference

### typo3-build.yaml

Builds PHP and optionally Node artifacts, uploads as build artifact.

| Input | Default | Description |
|-------|---------|-------------|
| `php_version` | `8.3` | PHP version |
| `node_version` | `20` | Node.js version |
| `build_frontend` | `false` | Run `npm ci && npm run build` |

### deployer-release-create.yaml

Downloads build artifact and runs `release:create <server>` without switching.

| Input | Default | Description |
|-------|---------|-------------|
| `server` | required | Target server (e.g., `stage`, `production`) |
| `php_version` | `8.3` | PHP version |
| `deployer_file` | `./build/deploy.php` | Path to deploy.php |
| `artifact_name` | `build-<sha>` | Build artifact name |

| Secret | Description |
|--------|-------------|
| `ssh_key` | SSH private key for deployment |

### deployer-release-switch.yaml

Downloads build artifact and runs `release:switch <server>` to activate a release.

| Input | Default | Description |
|-------|---------|-------------|
| `server` | required | Target server (e.g., `stage`, `production`) |
| `php_version` | `8.3` | PHP version |
| `deployer_file` | `./build/deploy.php` | Path to deploy.php |
| `artifact_name` | `build-<sha>` | Build artifact name |

| Secret | Description |
|--------|-------------|
| `ssh_key` | SSH private key for deployment |

### typo3-e2e-test.yaml

Runs Playwright E2E tests against a deployed environment.

| Input | Default | Description |
|-------|---------|-------------|
| `test_url` | required | URL to test against |
| `e2e_path` | `tests/e2e` | Path to E2E test directory |
| `run_visual_tests` | `true` | Run visual regression tests |
| `visual_tests_continue_on_error` | `true` | Continue if visual tests fail |

### typo3-staged-deploy.yaml (Wrapper)

All-in-one workflow: build → stage deploy → E2E tests → production deploy.

| Input | Default | Description |
|-------|---------|-------------|
| `stage_url` | required | URL for E2E tests |
| `php_version` | `8.3` | PHP version |
| `node_version` | `20` | Node.js version |
| `build_frontend` | `false` | Run npm build |
| `run_e2e_tests` | `true` | Run Playwright tests |
| `e2e_path` | `tests/e2e` | Path to E2E tests |
| `deployer_file` | `./build/deploy.php` | Path to deploy.php |
| `deploy_production` | `true` | Deploy to prod after tests pass |

| Secret | Description |
|--------|-------------|
| `stage_key` | SSH key for staging |
| `prod_key` | SSH key for production |

## Deployer Tasks

The shared recipe provides these tasks:

- `release:create <server>` - Upload release without switching (for staged deploys)
- `release:switch <server>` - Switch to uploaded release
- `deploy <server>` - Full deploy (create + switch)

## Migration Checklist

- [ ] Update project's `build/deploy.php` to use shared recipe
- [ ] Update project's `.forgejo/workflows/` to use reusable workflows
- [ ] Choose composable or wrapper pattern
- [ ] Test on staging first