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

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.

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.

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