---
title: "CI/CD: automatic deployment for TYPO3 projects"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:ci-cd-for-typo3-projects@main"
source: "Administration/Deployment/Automated/Index.rst"
rendered: "2026-09-20T15:52:37+00:00"
---

# CI/CD: automatic deployment for TYPO3 projects {#ci-cd-for-typo3-projects}

**Continuous Integration (CI)** and **Continuous Deployment/Delivery (CD)**
are development practices that automate the process of building, testing,
and deploying code. Implementing CI/CD for TYPO3 projects ensures higher
quality releases, faster feedback loops, and lower risk of introducing bugs.

-   [Why CI/CD for TYPO3?](https://docs.typo3.org/permalink/t3coreapi:why-ci-cd-for-typo3-1@main)
-   [Common CI/CD stages in TYPO3 projects](https://docs.typo3.org/permalink/t3coreapi:common-ci-cd-stages-in-typo3-projects@main)
-   [CI/CD platforms](https://docs.typo3.org/permalink/t3coreapi:ci-cd-platforms@main)
-   [Best practices during CI/CD](https://docs.typo3.org/permalink/t3coreapi:best-practices-during-ci-cd@main)

## Why CI/CD for TYPO3? {#why-ci-cd-for-typo3}

TYPO3 is a powerful, enterprise-level CMS written in PHP. TYPO3 projects
often involve custom extensions, configuration management (TypoScript, YAML config),
and complex deployment workflows. Manual deployment increases the risk of
human error, environment inconsistencies, and delayed releases. CI/CD
automates these concerns.

## Common CI/CD stages in TYPO3 projects {#ci-cd-common-stages}

### Code quality checks {#ci-cd-code-quality-checks}

-   **PHP Linting** (for example, `php -l`)
-   [Code style tests and fixing](https://docs.typo3.org/permalink/t3coreapi:testing-projects-configuration-cs@main)
-   **Static Analysis** (for example [PHPstan](https://docs.typo3.org/permalink/t3coreapi:testing-projects-configuration-phpstan@main) or Psalm)
-   Linting of other used formats like [TypoScript](https://github.com/martin-helmich/typo3-typoscript-lint), XML, and YAML.

### Unit and functional testing {#ci-cd-unit-functional-testing}

-   [Unit tests](https://docs.typo3.org/permalink/t3coreapi:testing-writing-unit@main)
-   [Functional tests](https://docs.typo3.org/permalink/t3coreapi:testing-writing-functional@main)
-   [Acceptance tests](https://docs.typo3.org/permalink/t3coreapi:testing-writing-acceptance@main)

### Building artifacts {#ci-cd-building-artifacts}

-   Installing required extensions and other PHP packages via Composer
-   Compile frontend assets (e.g., SCSS, JavaScript) using tools like
    Webpack, Gulp or Vite.

### Deployment {#ci-cd-deployment}

-   **File Synchronization**: Deploy code and assets using tools like [Rsync](https://docs.typo3.org/permalink/t3coreapi:deployment-rsync@main),
    [Deployer](https://docs.typo3.org/permalink/t3coreapi:deployment-deployer@main),
    or Git-based workflows.
-   **Database Migrations**: Run database migrations using TYPO3’s
    `vendor/bin/typo3 extension:setup` or
    `vendor/bin/typo3 database:updateschema` if [`helhum/typo3-console`](https://packagist.org/packages/helhum/typo3-console)
    is installed.
-   **Cache Clearing**: Clear TYPO3 caches
    (`vendor/bin/typo3 cache:flush`).

### Environment configuration {#ci-cd-environment-configuration}

Manage environment-specific settings using
[.env / dotenv files](https://docs.typo3.org/permalink/t3coreapi:environment-dotenv@main)
or [Plain PHP configuration files](https://docs.typo3.org/permalink/t3coreapi:environment-phpconfig@main).

### Typical CI/CD tools used {#ci-cd-typical-tools}

-   **CI/CD Platforms**

    [GitHub Actions](https://docs.typo3.org/permalink/t3coreapi:ci-cd-github@main),
    [GitLab CI](https://docs.typo3.org/permalink/t3coreapi:ci-cd-gitlab@main),
    [Jenkins](https://www.jenkins.io/), or [CircleCI](https://circleci.com/)

-   **Code Quality**

    [PHP-CS-Fixer](https://docs.typo3.org/permalink/t3coreapi:testing-projects-configuration-cs@main),
    [PHPstan](https://docs.typo3.org/permalink/t3coreapi:testing-projects-configuration-phpstan@main),
    and [TypoScript-Lint](https://github.com/martin-helmich/typo3-typoscript-lint)

-   **Testing**

    [PHPUnit](https://phpunit.de/) with the [TYPO3 Testing Framework](https://docs.typo3.org/permalink/t3coreapi:testing-writing-unit@main)

-   **Build Tools**

    Docker or Podman, Composer, Webpack, Gulp, or Vite

-   **Deployment Tools**

    [Deployer](https://docs.typo3.org/permalink/t3coreapi:deployment-deployer@main),
    [Rsync](https://docs.typo3.org/permalink/t3coreapi:deployment-rsync@main), Helm, Ansible, GitOps

## CI/CD platforms {#ci-cd-plattforms}

### Using GitLab CI {#ci-cd-gitlab}

The [Official GitLab template for TYPO3](https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/ProjectTemplates/GitLabTemplate/Index.html#gitlab-template)
provides a predefined [.gitlab-ci.yml](https://gitlab.com/gitlab-org/project-templates/typo3-distribution/-/blob/main/.gitlab-ci.yml)
and a [Deployer recipe](https://docs.typo3.org/permalink/t3coreapi:deployer-gitlab@main)
that you can customize to your needs.

Even if you already set up your project you can find valuable examples there.

### Using GitHub actions {#ci-cd-github}

In the following code-block you find a very simplified example of what
a deployment workflow with GitHub Actions might look like.

For a more life like example see [the .github-ci.yml of Stefan Frömken's TYPO3 Lexicon](https://github.com/froemken/typo3lexikon/blob/main/.github/workflows/.github-ci.yml).

**.github/workflows/.github-ci.yml**

```yaml
name: TYPO3 CI/CD Pipeline

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install Dependencies
        run: composer install --prefer-dist

      - name: Lint PHP
        run: find . -name "*.php" -exec php -l {} \;

      - name: Run PHPStan
        run: vendor/bin/phpstan analyse

      - name: Run PHPUnit Tests
        run: vendor/bin/phpunit

      - name: Deploy (Example)
        run: |
          ssh user@server 'cd /var/www/html && git pull && composer install \
          --no-dev && ./vendor/bin/typo3 cache:flush'

```

## Best practices during CI/CD {#ci-cd-best-practices}

1.  **Version Control Everything**

    Include `composer.json`, `composer.lock`, `config/`, `packages`, and
    deployment scripts.
1.  **Use Environment Variables**

    Never hardcode environment-specific values.
1.  **Keep Builds Reproducible**

    Lock dependencies with `composer.lock`.
1.  **Automate Database Migrations**

    Apply migrations as part of the deployment step.

    1.  **Fail Fast**

        Ensure the pipeline stops on errors in quality checks or tests.
    1.  **Use Staging Environments**

        Test changes in staging before promoting to production.