doc-locale/fr-fr/ci/components/examples.md
{{< details >}}
{{< /details >}}
Selon la fonctionnalité d'un composant, tester le composant peut nécessiter des fichiers supplémentaires dans le dépôt. Par exemple, un composant qui effectue du linting, de la compilation et des tests de logiciels dans un langage de programmation spécifique nécessite des exemples de code source réels. Vous pouvez inclure des exemples de code source, des fichiers de configuration et des éléments similaires dans le même dépôt.
Par exemple, le composant CI/CD Code Quality dispose de plusieurs exemples de code pour les tests.
Selon la fonctionnalité d'un composant, tester le composant peut nécessiter des fichiers supplémentaires dans le dépôt.
L'exemple « hello world » suivant pour le langage de programmation Rust utilise la chaîne d'outils cargo pour plus de simplicité :
Accédez au répertoire racine du composant CI/CD.
Initialisez un nouveau projet Rust en utilisant la commande cargo init.
cargo init
La commande crée tous les fichiers de projet nécessaires, notamment un exemple « hello world » src/main.rs. Cette étape est suffisante pour compiler le code source Rust dans un job de composant avec cargo build.
tree
.
├── Cargo.toml
├── LICENSE.md
├── README.md
├── src
│ └── main.rs
└── templates
└── build.yml
Assurez-vous que le composant dispose d'un job pour compiler le code source Rust, par exemple, dans templates/build.yml :
spec:
inputs:
stage:
default: build
description: 'Defines the build stage'
rust_version:
default: latest
description: 'Specify the Rust version, use values from https://hub.docker.com/_/rust/tags Defaults to latest'
---
"build-$[[ inputs.rust_version ]]":
stage: $[[ inputs.stage ]]
image: rust:$[[ inputs.rust_version ]]
script:
- cargo build --verbose
Dans cet exemple :
stage et rust_version peuvent être modifiées par rapport à leurs valeurs par défaut. Le job CI/CD commence par un préfixe build- et crée dynamiquement le nom en fonction de l'entrée rust_version. La commande cargo build --verbose compile le code source Rust.Testez le modèle build du composant dans le fichier de configuration .gitlab-ci.yml du projet :
include:
# include the component located in the current project from the current SHA
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/build@$CI_COMMIT_SHA
inputs:
stage: build
stages: [build, test, release]
Pour exécuter des tests et plus encore, ajoutez des fonctions et des tests supplémentaires dans le code Rust, et ajoutez un modèle de composant et un job exécutant cargo test dans templates/test.yml.
spec:
inputs:
stage:
default: test
description: 'Defines the test stage'
rust_version:
default: latest
description: 'Specify the Rust version, use values from https://hub.docker.com/_/rust/tags Defaults to latest'
---
"test-$[[ inputs.rust_version ]]":
stage: $[[ inputs.stage ]]
image: rust:$[[ inputs.rust_version ]]
script:
- cargo test --verbose
Testez le job supplémentaire dans le pipeline en incluant le modèle de composant test :
include:
# include the component located in the current project from the current SHA
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/build@$CI_COMMIT_SHA
inputs:
stage: build
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/test@$CI_COMMIT_SHA
inputs:
stage: test
stages: [build, test, release]
Cette section fournit des exemples pratiques d'implémentation de modèles courants dans les composants CI/CD.
Vous pouvez composer des jobs avec deux conditions en combinant des entrées de type boolean et la fonctionnalité extends.
Par exemple, pour configurer un comportement de mise en cache complexe avec une entrée boolean :
spec:
inputs:
enable_special_caching:
description: 'If set to `true` configures a complex caching behavior'
type: boolean
---
.my-component:enable_special_caching:false:
extends: null
.my-component:enable_special_caching:true:
cache:
policy: pull-push
key: $CI_COMMIT_SHA
paths: [...]
my-job:
extends: '.my-component:enable_special_caching:$[[ inputs.enable_special_caching ]]'
script: ... # run some fancy tooling
Ce modèle fonctionne en transmettant l'entrée enable_special_caching dans le mot-clé extends du job. Selon que enable_special_caching est true ou false, la configuration appropriée est sélectionnée parmi les jobs masqués prédéfinis (.my-component:enable_special_caching:true ou .my-component:enable_special_caching:false).
options pour configurer conditionnellement des jobs {#use-options-to-conditionally-configure-jobs}Vous pouvez composer des jobs avec plusieurs options, pour un comportement similaire aux conditions if et elseif. Utilisez extends avec le type string et plusieurs options pour un nombre quelconque de conditions.
Par exemple, pour configurer un comportement de mise en cache complexe avec 3 options différentes :
spec:
inputs:
cache_mode:
description: Defines the caching mode to use for this component
type: string
options:
- default
- aggressive
- relaxed
---
.my-component:cache_mode:default:
extends: null
.my-component:cache_mode:aggressive:
cache:
policy: push
key: $CI_COMMIT_SHA
paths: ['*/**']
.my-component:cache_mode:relaxed:
cache:
policy: pull-push
key: $CI_COMMIT_BRANCH
paths: ['bin/*']
my-job:
extends: '.my-component:cache_mode:$[[ inputs.cache_mode ]]'
script: ... # run some fancy tooling
Dans cet exemple, l'entrée cache_mode propose les options default, aggressive et relaxed, chacune correspondant à un job masqué différent. En étendant le job du composant avec extends: '.my-component:cache_mode:$[[ inputs.cache_mode ]]', le job hérite dynamiquement de la configuration de mise en cache correcte en fonction de l'option sélectionnée.
{{< history >}}
ci_component_context_interpolation. Activé par défaut.ci_component_context_interpolation a été supprimé.{{< /history >}}
Utilisez les expressions CI/CD du contexte de composant pour référencer les métadonnées du composant, comme la version et le SHA du commit. Un cas d'utilisation consiste à compiler et publier des ressources versionnées (comme des images Docker) avec votre composant, et à s'assurer que le composant utilise la version correspondante.
Par exemple, vous pouvez :
Dans le pipeline de release du projet de composant (.gitlab-ci.yml) :
build-image:
stage: build
image: docker:latest
script:
- docker build -t $CI_REGISTRY_IMAGE/my-tool:$CI_COMMIT_TAG .
- docker push $CI_REGISTRY_IMAGE/my-tool:$CI_COMMIT_TAG
create-release:
stage: release
image: registry.gitlab.com/gitlab-org/cli:latest
script: echo "Creating release $CI_COMMIT_TAG"
rules:
- if: $CI_COMMIT_TAG
release:
tag_name: $CI_COMMIT_TAG
description: "Release $CI_COMMIT_TAG"
Dans le modèle de composant (templates/my-component/template.yml) :
spec:
component: [version, reference]
inputs:
stage:
default: test
---
run-tool:
stage: $[[ inputs.stage ]]
image: $CI_REGISTRY_IMAGE/my-tool:$[[ component.version ]]
script:
- echo "Running tool version $[[ component.version ]]"
- echo "Component was included using reference: $[[ component.reference ]]"
- my-tool --version
Dans cet exemple :
@1.0.0, le job utilise l'image my-tool:1.0.0.@1.0, il se résout vers la dernière version 1.0.x, par exemple 1.0.3, et utilise donc my-tool:1.0.3.@~latest, il utilise la dernière version publiée.component.reference affiche la référence exacte que vous avez spécifiée, comme 1.0, ~latest, ou un SHA. La référence peut être utile pour la journalisation ou le débogage.Cette section présente des exemples pratiques de migration de modèles CI/CD et de configurations de pipeline vers des composants CI/CD réutilisables.
Un pipeline complet pour le cycle de vie du développement logiciel peut être composé de plusieurs jobs et étapes. Les modèles CI/CD pour les langages de programmation peuvent fournir plusieurs jobs dans un seul fichier de modèle. À titre d'exercice, le modèle CI/CD Go suivant doit être migré.
default:
image: golang:latest
stages:
- test
- build
- deploy
format:
stage: test
script:
- go fmt $(go list ./... | grep -v /vendor/)
- go vet $(go list ./... | grep -v /vendor/)
- go test -race $(go list ./... | grep -v /vendor/)
compile:
stage: build
script:
- mkdir -p mybinaries
- go build -o mybinaries ./...
artifacts:
paths:
- mybinaries
[!note] Pour une approche plus incrémentale, migrez un job à la fois. Commencez par le job
build, puis répétez les étapes pour les jobsformatettest.
La migration du modèle CI/CD implique les étapes suivantes :
Analysez les jobs CI/CD et leurs dépendances, et définissez les actions de migration :
image est globale et doit être déplacée dans les définitions de job.format exécute plusieurs commandes go dans un seul job. La commande go test doit être déplacée dans un job séparé pour améliorer l'efficacité du pipeline.compile exécute go build et doit être renommé build.Définissez des stratégies d'optimisation pour améliorer l'efficacité du pipeline.
stage doit être configurable pour permettre à différents consommateurs de pipeline CI/CD de l'utiliser.image utilise un tag d'image codé en dur latest. Ajoutez golang_version comme entrée avec latest comme valeur par défaut pour des pipelines plus flexibles et réutilisables. L'entrée doit correspondre aux valeurs de tag d'image Docker Hub.compile compile les binaires dans un répertoire cible codé en dur mybinaries, qui peut être amélioré avec une entrée dynamique et la valeur par défaut mybinaries.Créez une structure de répertoires de modèle pour le nouveau composant, basée sur un modèle par job.
go, par exemple format.yml, build.yml et test.yml.README.md, LICENSE.md, .gitlab-ci.yml, .gitignore. Les commandes shell suivantes initialisent la structure du composant Go :git init
mkdir templates
touch templates/{format,build,test}.yml
touch README.md LICENSE.md .gitlab-ci.yml .gitignore
git add -A
git commit -avm "Initial component structure"
git remote add origin https://gitlab.example.com/components/golang.git
git push
Créez les jobs CI/CD en tant que modèle. Commencez par le job build.
Définissez les entrées suivantes dans la section spec : stage, golang_version et binary_directory.
Ajoutez une définition de nom de job dynamique, en accédant à inputs.golang_version.
Utilisez le même modèle pour les versions d'images Go dynamiques, en accédant à inputs.golang_version.
Assignez l'étape à la valeur inputs.stage.
Créez le répertoire de binaires à partir de inputs.binary_directory et ajoutez-le comme paramètre à go build.
Définissez le chemin des artefacts vers inputs.binary_directory.
spec:
inputs:
stage:
default: 'build'
description: 'Defines the build stage'
golang_version:
default: 'latest'
description: 'Go image version tag'
binary_directory:
default: 'mybinaries'
description: 'Output directory for created binary artifacts'
---
"build-$[[ inputs.golang_version ]]":
image: golang:$[[ inputs.golang_version ]]
stage: $[[ inputs.stage ]]
script:
- mkdir -p $[[ inputs.binary_directory ]]
- go build -o $[[ inputs.binary_directory ]] ./...
artifacts:
paths:
- $[[ inputs.binary_directory ]]
Le modèle de job format suit les mêmes modèles, mais ne nécessite que les entrées stage et golang_version.
spec:
inputs:
stage:
default: 'format'
description: 'Defines the format stage'
golang_version:
default: 'latest'
description: 'Golang image version tag'
---
"format-$[[ inputs.golang_version ]]":
image: golang:$[[ inputs.golang_version ]]
stage: $[[ inputs.stage ]]
script:
- go fmt $(go list ./... | grep -v /vendor/)
- go vet $(go list ./... | grep -v /vendor/)
Le modèle de job test suit les mêmes modèles, mais ne nécessite que les entrées stage et golang_version.
spec:
inputs:
stage:
default: 'test'
description: 'Defines the format stage'
golang_version:
default: 'latest'
description: 'Golang image version tag'
---
"test-$[[ inputs.golang_version ]]":
image: golang:$[[ inputs.golang_version ]]
stage: $[[ inputs.stage ]]
script:
- go test -race $(go list ./... | grep -v /vendor/)
Pour tester le composant, modifiez le fichier de configuration .gitlab-ci.yml et ajoutez des tests.
Spécifiez une valeur différente pour golang_version comme entrée pour le job build.
Modifiez l'URL pour le chemin de votre composant CI/CD.
stages: [format, build, test]
include:
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/format@$CI_COMMIT_SHA
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/build@$CI_COMMIT_SHA
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/build@$CI_COMMIT_SHA
inputs:
golang_version: "1.21"
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/test@$CI_COMMIT_SHA
inputs:
golang_version: latest
Ajoutez du code source Go pour tester le composant CI/CD. Les commandes go attendent un projet Go avec go.mod et main.go dans le répertoire racine.
Initialisez les modules Go. Modifiez l'URL pour le chemin de votre composant CI/CD.
go mod init example.gitlab.com/components/golang
Créez un fichier main.go avec une fonction principale affichant Hello, CI/CD component par exemple. Vous pouvez utiliser des commentaires de code pour générer du code Go à l'aide de GitLab Duo Code Suggestions.
// Specify the package, import required packages
// Create a main function
// Inside the main function, print "Hello, CI/CD Component"
package main
import "fmt"
func main() {
fmt.Println("Hello, CI/CD Component")
}
L'arborescence du répertoire doit se présenter comme suit :
tree
.
├── LICENSE.md
├── README.md
├── go.mod
├── main.go
└── templates
├── build.yml
├── format.yml
└── test.yml
Suivez les étapes restantes dans la section conversion d'un modèle CI/CD en composant pour finaliser la migration :
README.md et LICENSE.md.Le composant Go maintenu par GitLab fournit un exemple de migration réussie à partir d'un modèle CI/CD Go, enrichi d'entrées et des meilleures pratiques en matière de composants. Vous pouvez inspecter l'historique Git pour en savoir plus.