Sources Git et Build Workers

Configurez le connecteur à l’aide de Hébergement Git. Ce guide distingue aussi les permissions sur les dépôts des permissions sur les cibles nécessaires pour lancer des builds enregistrés et lire leur historique. Les identifiants de registres sont traités dans Registres de conteneurs.

La prise en charge des sources Git relie une révision de dépôt approuvée à un artefact de build immuable. Elle peut alimenter un Container, un Deployment, un projet Compose Docker ou une version Pages, mais la charge de travail obtenue suit toujours le cycle de vie de sa ressource propriétaire. Une connexion de source n’est pas, en elle-même, une permission de modifier une route de production ou une cible de trafic.

Décider de ce que l’automatisation a le droit de faire

Séparez trois décisions : qui peut lire la source, ce qui constitue un artefact approuvé, et si cet artefact peut être déployé automatiquement. Les garder séparées permet à une équipe d’automatiser les publications courantes sans donner à un webhook de dépôt une autorité illimitée sur la production.

Le responsable de la source contrôle l’accès au dépôt et le commit à construire. Le responsable de la plateforme contrôle le Build Worker, la politique de build, le registre et la cible de déploiement. Le responsable du service définit la recette et le retour arrière. Opfield relie ces enregistrements et préserve la provenance du commit à l’empreinte, mais un build réussi reste seulement une entrée pour une publication.

Utilisez le build automatique lorsque chaque modification de la source sélectionnée doit produire un artefact. N’activez le déploiement automatique qu’une fois que la ressource propriétaire dispose d’un contrôle de santé et d’un chemin de reprise testés, et uniquement pour les branches dont le modèle de contrôle des changements le permet. Pour les services plus risqués, gardez l’approbation de l’artefact et le déploiement comme deux décisions humaines distinctes.

Prérequis et propriété

Utilisez une intégration de sources prise en charge et figurant sur la liste d’autorisation, et n’autorisez que l’accès au dépôt nécessaire au build. Sélectionnez une révision de branche exacte, puis vérifiez que le Build Worker dédié attribué est en ligne. Le worker exécute un build à la fois par défaut (Parallel jobs sur sa page de nœud, jusqu’à 16), utilise un état BuildKit et containerd isolé, applique des limites de ressources fixes, refuse les droits de build non sécurisés et vide le cache entre les tâches. Un hôte Build Worker nécessite systemd.

Les builds en file d’attente vont aux Build Workers dans l’ordre où ils apparaissent dans la liste Nodes : le premier worker en ligne prend les builds jusqu’à ce que toutes ses tâches parallèles soient occupées, puis le suivant prend le relais. Faites glisser un worker plus haut pour le privilégier, ou tout en bas pour le réserver aux débordements. L’ordre de la liste est le suivant : les dossiers de premier niveau selon leur position, à l’intérieur d’un dossier ses sous-dossiers d’abord puis ses nœuds, et les nœuds hors de tout dossier en dernier. Un worker ne prend que les builds de sa propre plateforme (architecture).

Les Build Secrets sont limités à la source et montés comme secrets pendant le build. Ne placez pas d’identifiants dans les arguments de build, les références d’images, les URL de dépôts, la configuration commitée ou les journaux. Le Build Worker détient l’isolation de l’exécution ; le registre détient l’artefact produit ; le nœud Docker cible récupère et exécute ensuite cet artefact.

Construire et examiner l’artefact

1. Connectez l’intégration et choisissez le dépôt, la branche et la révision prévue.
2. Configurez l’entrée du build et les secrets limités à la source.
3. Lancez le build et suivez sa tâche, de l’attribution du worker à la publication de l’artefact.
4. Examinez les journaux masqués, les constats de vulnérabilités, le résultat de la politique, le commit source et l’empreinte immuable de l’artefact.
5. Sélectionnez l’empreinte approuvée dans le processus du Container, du Deployment ou de Pages propriétaire.

Pendant le déploiement d’un build sur un Container, un Deployment ou un projet Compose, Opfield verrouille cette cible : les changements de cycle de vie et de configuration, les changements de secrets, les changements d’Availability et les migrations sont refusés avec BUILD_ROLLOUT_IN_PROGRESS jusqu’à ce que le déploiement réussisse, échoue ou soit annulé, et la Console affiche un bandeau sur la cible. Le verrou survit à un redémarrage d’Opfield. Si la cible est occupée par une autre opération au début du déploiement, celui-ci attend jusqu’à 5 minutes puis échoue avec BUILD_ROLLOUT_TARGET_BUSY. Les versions Pages ne sont pas verrouillées de cette façon. Pendant une mise à jour d’Opfield, les builds déclenchés par webhook ou par interrogation périodique sont différés et démarrent une fois après la mise à jour.

Sync now, sur la source Git d’un Container, d’un Deployment, d’un projet Compose ou d’un projet Pages, vérifie immédiatement la branche et lance un build si elle a avancé et que les builds automatiques sont activés. La politique de vulnérabilités de la source refuse les artefacts dont les constats atteignent ou dépassent la sévérité sélectionnée (Critical par défaut, ou High, Medium ou Low) ; None approuve chaque artefact analysé, et Disabled approuve les artefacts sans exiger d’analyse. Les résultats des builds sont envoyés au registre sans être conservés dans le magasin d’images propre au worker ; les builds ne remplissent donc pas le disque du worker.

Le build automatique et le déploiement automatique sont des contrôles indépendants. Gardez le déploiement automatique désactivé jusqu’à ce que le chemin de santé et de retour arrière ait fait ses preuves pour cette charge de travail. Un build réussi prouve seulement qu’un artefact existe ; il ne prouve pas que l’application démarre correctement sur un nœud cible.

Placement des charges de travail construites dans les dossiers

Un Container ou un Deployment créé à partir d’une source Git est placé dans le dossier choisi à sa création : le champ de dossier de l’onglet Repository de la boîte de dialogue de déploiement, ou folderId via l’API et MCP. Sa création à cet endroit nécessite la permission de création sur ce dossier, et un utilisateur qui ne peut créer que dans des dossiers doit en choisir un ; la boîte de dialogue présélectionne le seul dossier autorisé. La configuration de la source nécessite aussi integrations:<provider>:use sur le dépôt ; voir Hébergement Git.

Jusqu’à la fin de son premier build, la charge de travail est listée dans ce dossier avec Awaiting build à la place d’une image. Elle peut être déplacée comme n’importe quel autre conteneur : avec Move to folder…, par glisser-déposer, ou via l’API et MCP, ce qui nécessite la permission de modification sur la charge de travail et sur la destination. Le premier build la crée dans le dossier où elle se trouve à ce moment-là et y vérifie la permission de création, y compris lorsque c’est l’automatisation de la source qui lance le build. Un utilisateur limité à des dossiers ne se retrouve donc jamais avec une charge de travail construite à la racine. Le nom reste réservé à la source pendant ce temps : créer, dupliquer, renommer ou importer un autre conteneur sous ce nom échoue avec 409 NAME_IN_USE.

Gestion des échecs

Si un build ne peut pas démarrer, vérifiez l’autorisation de la source, la disponibilité des workers, les droits du plan et l’état de l’intégration. Les builds utilisent l’identifiant du connecteur et ne dépendent pas des scopes Git actuels de qui que ce soit : integrations:<provider>:use sur le dépôt n’est nécessaire que pour connecter la source ou modifier son connecteur, son dépôt ou sa branche ; voir Qui peut lancer des builds et consulter les résultats ?. S’il échoue après son démarrage, utilisez la phase et les journaux pour distinguer les échecs de dépendances, de secrets, de politique, de définition du build ou de publication de l’artefact. Corrigez la source ou la configuration du build, puis lancez un nouveau build. Une nouvelle tentative crée une nouvelle opération et préserve l’historique précédent.

Lorsque le worker ou l’automatisation de la source est indisponible, l’historique existant reste utile au diagnostic, mais il ne faut pas supposer que de nouveaux builds s’exécutent. Ne substituez pas un tag d’image modifiable à l’artefact immuable manquant ; attendez un build vérifié ou utilisez une image approuvée séparément.

Disponibilité après un déploiement

Lorsqu’un build est déployé sur un Container, Opfield le recrée avec la nouvelle image et attend jusqu’à 60 secondes qu’il devienne prêt : sain lorsque l’image comporte une vérification de santé, sinon en cours d’exécution pendant 10 secondes sans redémarrage. Un conteneur qui redémarre en boucle, se termine ou devient défaillant est ramené à son image précédente, et le build échoue avec BUILD_ROLLOUT_ROLLED_BACK, ou BUILD_ROLLOUT_ROLLBACK_FAILED lorsque l’image précédente n’a pas pu être restaurée. L’erreur indique l’état du conteneur, le code de sortie et le nombre de redémarrages, suivis des dernières lignes de son journal, et le commit déployé reste le précédent. Les autres échecs de déploiement sont signalés comme BUILD_ROLLOUT_FAILED. Un Deployment utilise son propre chemin blue/green contrôlé par des vérifications de santé : un candidat en échec est arrêté et le trafic reste sur le slot actif. Une révision Compose construite depuis Git dont un port publié est déjà détenu par une autre charge de travail sur le nœud échoue avec COMPOSE_HOST_PORT_IN_USE, et aucune révision n’est créée.

Nettoyage et retour arrière

Retirer une connexion de source empêche le travail futur piloté par la source, mais ne supprime pas automatiquement une exécution déjà déployée ni son artefact. Supprimer un conteneur supprime sa source Git, et lorsque le webhook de dépôt d’un conteneur supprimé ne peut pas être supprimé, sa source cesse de construire et de déployer, afin qu’un nouveau commit ne puisse pas recréer le conteneur ; le nettoyage est retenté plus tard. Les images de build des Containers, Deployments et projets Compose supprimés sont retirées automatiquement de leurs nœuds, généralement en moins d’une minute, et les nœuds qui étaient hors ligne sont revérifiés toutes les 10 minutes. Une image de build inutilisée peut aussi être supprimée à la main depuis les images du nœud ; la suppression d’une image encore utilisée par un conteneur du nœud est refusée avec 409 OPFIELD_INTERNAL_IMAGE. Avant de révoquer la connexion, décidez quels artefacts restent nécessaires pour un retour arrière. La conservation des artefacts est régie par le registre et par l’historique actif, de retour arrière, en cours, épinglé et des réussites récentes de la ressource propriétaire.

Critères de réussite

Un build acceptable identifie le dépôt et le commit exact, se termine sur un worker approuvé, produit une empreinte immuable, passe la politique de vulnérabilités configurée et expose des journaux sans secrets. La recette du déploiement est distincte : la ressource cible doit récupérer cette empreinte, démarrer avec succès, passer la vérification de santé et servir le chemin client attendu.

Conservez suffisamment d’historique de builds et d’artefacts pour expliquer ce qui s’exécute et pour restaurer la version précédente réputée saine. Un tag modifiable, un journal de console réussi ou un badge de build au vert sans l’empreinte ne constituent pas une preuve suffisante en production.

Détails pour l’opérateur : isolation et diagnostic

Les Build Workers sont des frontières d’exécution dédiées, car le contenu des dépôts et les définitions de build peuvent exécuter du code. Gardez les identifiants des workers restreints, ne placez pas sur le même hôte des charges de travail sensibles sans rapport, et considérez la sortie des builds comme non fiable jusqu’à la fin des vérifications de politique et de provenance. Les Build Secrets ne doivent être montés que pour l’étape de build qui en a besoin et ne doivent pas être copiés dans les couches de l’image.

Les étapes de build ne peuvent pas joindre l’hôte du Build Worker lui-même, en IPv4 comme en IPv6, quel que soit le profil de trafic sortant (internet ou offline). Sur un hôte doté d’IPv6, le worker a besoin d’ip6tables et ne démarre pas sans lui.

Lorsqu’un build est en file d’attente, distinguez le manque de capacité des workers d’un échec de source ou de politique. Lorsqu’il s’exécute et échoue, identifiez la phase : récupération de la source, résolution des dépendances, build Dockerfile ou Compose, admission des vulnérabilités, publication dans le registre ou acquittement final. Conservez le journal limité et le commit avant de réessayer. Une nouvelle tentative doit créer un nouvel essai auditable plutôt que d’écraser l’enregistrement en échec.