CI/CD

Pro automatickou integraci a nasazení využíváme Jenkins, který je hostovaný na našem serveru na adrese jenkins.webserver.esoul.cz. Je integrovaný přímo s naším GitHubem, takže se spouští automaticky a využívá OAuth pro přihlášení (přihlašujete se svým Github účtem).

Definice pipeline

Pipeline je definována v souboru Jenkinsfile, který je umístěn v kořenovém adresáři každého repozitáře.

Pipeline má následující základní strukturu:

pipeline {
    agent any

    environment {
        // Define environment variables here
    }

    stages {
        // Prepare
        // Test
        // Build
        // Deploy staging (if in staging branch)
        // Deploy production (if in production branch)
    }
    
    post {
        always {
            // Actions that always run after the stages, e.g., cleanup
        }
        success {
            // Actions that run on successful completion, e.g., notifications
            echo 'Pipeline completed successfully!'
        }
        failure {
            // Actions that run on failure, e.g., notifications
            echo 'Pipeline failed!'
        }
    }
}

Všechny hesla, klíče a další citlivé údaje by měly být uloženy jako Jenkins Credentials, aby nebyly přímo v Jenkinsfile.
Všechny statické hodnoty by měly být definovány jako proměnné v environment bloku.
- Alternativně je možné použít i argumenty pipeline, které se předávají při spuštění. (to slouží ale jen pro manuální spuštění pipeline)
Používejte agent any, pokud není potřeba specifický agent pro danou pipeline.
Pipeline by měla být rozdělena do několika stage, které reprezentují jednotlivé kroky procesu (např. build, test, deploy).
Stage se pouštějí sekvenčně, ale je možné je spouštět paralelně pomocí parallel direktivy.
Deploy (staging a produkce) by měli mít vlastní stage, které se spouští jen na konkrétních větvích pomocí when direktivy (např. main pro produkci a develop pro staging).

Pomocné sdílené knihovny

V Jenkins je nadefinováno několik sdílených knihoven, které obsahují předdefinované funkce pro usnadnění práce s Jenkins pipeline.

Všechny definice knihoven jsou dostupné na našem GitHubu (pravděpodobně tam nemáte přístup).

Pokud chcete využít některou z knihoven, stačí ji naimportovat do vašeho Jenkinsfile pomocí direktivy @Library.

@Library('<nazev_knihovny>') _

Pokud chcete využít více knihoven najednou, musíte je importovat všechny najednou v jednom řádku:

@Library(['knihovna1', 'knihovna2']) _

Deploy

Pomocná knihovna s předdefinovanými funkcemi pro nasazení aplikací v Jenkins pipeline.

@Library('deploy') _

Dostupné funkce:

deployToServer

Funkce pro nahrání statických souborů do adresáře na server.

Parameter	Required	Default	Description
`sourceDir`	Yes	-	Local directory to deploy (e.g., 'output/')
`deployServer`	No	'localhost'	Target server hostname or IP address
`deployUser`	No	'deploy'	SSH user for deployment
`deployPath`	Yes	-	Destination path on server
`groupOwner`	No	'apps'	Group to set ownership to
`permissions`	No	'755'	File permissions to set (chmod)
`createBackup`	No	true	Whether to backup existing files before deployment
`deleteExisting`	No	true	Whether to delete files not in source (rsync --delete)

Příklad:

Nahraje obsah adresáře output/ na vzdálený server pomocí SSH klíče uloženého v Jenkins Credentials pod ID deploy_ssh.

script {
    sshagent(credentials: ['deploy_ssh']) {
        deployToServer(
            sourceDir: 'output/',
            deployServer: env.DEPLOY_SERVER,
            deployUser: env.DEPLOY_USER,
            deployPath: env.DEPLOY_PATH,
            groupOwner: 'apps',
            permissions: '755',
            createBackup: false,
            deleteExisting: true
        )
    }
}

dockerHelpers

Pomocná knihovna s předdefinovanými funkcemi pro práci s Dockerem v Jenkins pipeline.

@Library('dockerHelpers') _

Dostupné funkce:

dockerRegistryLogin

Pomocná funkce pro přihlášení do Docker registry v Jenkins pipeline.

Parameter	Required	Default	Description
`registryUrl`	No	`rg.fr-par.scw.cloud/testing-images`	URL of the Docker registry (e.g., 'https://index.docker.io/v1/')
`username`	No	-	Docker registry username
`password`	Yes	-	Docker registry password or token

Příklad:

Přihlásí se do Scaleway Docker registry, pomocí tajného klíče uloženého v Jenkins Credentials.

script {
    withCredentials([string(credentialsId: 'scaleway_secret_key', variable: 'SECRET')]) {
        dockerRegistryLogin(
            registryUrl: TEST_REGISTRY,
            password: env.SECRET
        )
    }
}

Doporučuje se přidat i odhlášení do post bloku:

post {
    always {
        dockerRegistryLogout TEST_REGISTRY
    }
}

dockerRegistryLogout

Pomocná funkce pro odhlášení z Docker registry v Jenkins pipeline. Vhodná pro použití v post bloku.

Parameter	Required	Default	Description
`registryUrl`	No	`rg.fr-par.scw.cloud/testing-images`	URL of the Docker registry (e.g., 'https://index.docker.io/v1/')

Příklad:

dockerRegistryLogout TEST_REGISTRY

Testing

Pomocná knihovna pro usnadnění spouštění testů v Jenkins pipeline.

@Library('testing') _

Dostupné funkce:

runCommandInTest

Pomocná funkce pro spuštění libovolného příkazu v Docker kontejneru.

Parameter	Required	Default	Description
command	Yes	None	The command or script to be executed in the test environment.
image	Yes	None	The Docker image to use for the test environment.
options	No	None	Additional options to pass to the docker run command.

Příklad:

Spustí composer install v Docker kontejneru s PHP 8.5.

runCommandInTest(
    image: 'rg.fr-par.scw.cloud/testing-images/php:8.5',
    command: 'composer install --no-interaction --prefer-dist --optimize-autoloader',
)

Předchozí příklad je ekvivalentní k tomuto:

docker run --rm \ 
  -v $(pwd):/workspace \
  -w /workspace \
  rg.fr-par.scw.cloud/testing-images/php:8.5 \
  /bin/sh -c "composer install --no-interaction --prefer-dist --optimize-autoloader"

fullPhpTest

Pomocná funkce pro spuštění kompletního testování PHP aplikace v Docker kontejneru.

Spouští:

Composer install
Composer.json verify
PHPStan analýzu
PHPUnit testy
PHP CodeSniffer kontrolu

Parameter	Type	Required	Default	Description
`image`	string	yes	-	Docker image containing the PHP environment (e.g., 'php:8.1-cli')
`install`	boolean	no	`true`	Whether to run composer install
`composerValidate`	boolean	no	`true`	Whether to run composer validate
`phpstan`	boolean	no	`true`	Whether to run PHPStan static analysis
`cs`	boolean	no	`true`	Whether to run PHP CodeSniffer
`test`	boolean	no	`true`	Whether to run PHPUnit tests
`phpstanOptions`	string	no	-	Additional options for the phpstan docker run command
`csOptions`	string	no	-	Additional options for the phpcs docker run command
`testOptions`	string	no	-	Additional options for the phpunit docker run command
`phpstanCommand`	string	no	`composer run phpstan`	Command to run PHPStan
`csCommand`	string	no	`composer run cs`	Command to run PHP CodeSniffer
`testCommand`	string	no	`composer run test`	Command to run PHPUnit tests

Příklady:

Spustí kompletní testování PHP aplikace v Docker kontejneru pro připravený image php:8.5.

fullPhpTest(
    image: "rg.fr-par.scw.cloud/testing-images/php:8.5",
)

Testování Laravel aplikace:

fullPhpTest(
    image: "rg.fr-par.scw.cloud/testing-images/php:8.5",
    phpstanCommand: './vendor/bin/phpstan analyse --memory-limit=2G',
    csCommand: './vendor/bin/pint --test',
    testOptions: '-e APP_ENV=testing -e DB_CONNECTION=sqlite -e DB_DATABASE=:memory:',
    testCommand: 'cp .env.example .env && php artisan key:generate --ansi && php artisan config:clear && php artisan test --parallel'
)

Docker image pro testování

Testy se nespouštění přímo v agentu Jenkins, ale je potřeba využít konkrétní Docker image, který má všechny potřebné nástroje a závislosti pro spuštění testů.

Docker image jsou dostupné v našem Docker hub repozitáři hostovaném u Scaleway: rg.fr-par.scw.cloud/testing-images

Všechny Dockerfile s definicemi jsou dostupné na našem GitHubu: ci-images.

Momentálně máme dostupné tyto image (dostupné pro architektury: amd64 a arm64):

php - vychází z oficiálního php-apline-cli, nainstalovaný composer a většina běžných rozšíření
- :8.4
- :8.5, :8 :latest
node - vychází z oficiálního node-alpine, nainstalovaný npm a pnpm
- :24
- :25
- :lts, :latest

Sestavení produkčního docker image aplikace

Všechny aplikační Docker image by měly být nahrávány do našeho Docker hub repozitáře hostovaném u Scaleway: rg.fr-par.scw.cloud/app-images.

Sestavení probíhá v Jenkins pipeline.
Výsledný image by měl být označen tagem odpovídajícím verzi aplikace (např. 1.0.0, 1.2.3, atd.) a také tagem latest, který vždy ukazuje na nejnovější verzi.
Název image by měl výstižně odpovídat názvu aplikace.
Výsledný image musí být samostatně spustitelný (musí obsahovat všechny potřebné závislosti a konfigurace).
Výsledný image by měl být optimalizován pro co nejmenší velikost a pro produkční prostředí.

26 January 2026