Hébergement Git

Les intégrations Git déterminent à partir de quels dépôts Opfield peut construire. Un commit précis peut être suivi, via son build, jusqu’à un artefact immuable et jusqu’à la version qui l’exécute.

Configurez les intégrations de sources dans Settings > Integrations. Les fournisseurs pris en charge sont GitLab, GitHub et Git générique. Les connecteurs GitHub et Git générique sont disponibles avec tous les plans ; l’intégration GitLab, y compris la découverte des registres GitLab, nécessite Personal ou supérieur. Les connecteurs GitLab créés en Community avant 2.11 sont conservés, mais ne peuvent pas être ouverts tant qu’une clé Personal ou supérieure n’est pas active. Les builds à partir de sources Git nécessitent Business ou Enterprise. Pour l’accès à un système d’exploitation distant, utilisez le guide distinct des connexions SSH.

Utilisez une identité machine ou applicative dédiée avec un accès aux dépôts en lecture seule, sauf si un processus exige explicitement davantage. Restreignez les dépôts et les hôtes autorisés. Vérifiez l’authenticité des webhooks, la sélection des branches, la résolution des commits et la rotation des identifiants.

Les URL de dépôts ne doivent pas contenir d’identifiants intégrés. La vérification des clés d’hôte SSH et des certificats HTTPS doit échouer de manière fermée. Ne retirez une intégration qu’après avoir identifié et migré les sources Docker, Compose et Pages dépendantes.

Types d’intégration

• GitLab : découverte des projets et des groupes, opérations sur les dépôts, webhooks, variables, processus liés à la CI et découverte facultative des registres selon les droits.
• GitHub : découverte des dépôts et opérations prises en charge sur les dépôts et Actions via l’application ou le jeton configurés.
• Git générique : accès authentifié et borné aux dépôts lorsqu’un fournisseur de premier plan n’est pas nécessaire.

GitLab

1. Utilisez un utilisateur GitLab dédié qui n’est membre que des groupes et projets nécessaires. Dans GitLab, ouvrez le menu de l’avatar, Edit profile > Access > Personal access tokens. Créez un jeton (l’interface peut l’appeler legacy personal access token).
2. Définissez son nom et son expiration, puis choisissez les permissions dans le tableau. Copiez immédiatement le secret.
3. Dans l’intégration GitLab d’Opfield, saisissez l’origine de l’instance, par exemple https://gitlab.example.com, sans /api/v4, ainsi que le jeton. Sélectionnez les projets et groupes autorisés plutôt que d’accorder tous les projets découverts.
4. Testez le jeton, découvrez un projet autorisé et vérifiez l’accès au dépôt et à la branche. Un deploy token GitLab ne remplace pas cette identité d’API.

Processus	Scopes du jeton GitLab
Découvrir des projets et lire les métadonnées de l’API	read_api
Lire ou cloner les sources des dépôts pour les builds	read_repository avec read_api pour le connecteur de premier plan
Découvrir et récupérer des images de registres privés	Ajoutez read_registry et l’appartenance nécessaire au projet
Écrire des fichiers via l’API, gérer des hooks et des variables, ou effectuer des modifications de CI	api ; l’utilisateur doit aussi avoir le rôle requis sur le projet
Envoyer (push) via Git sur HTTPS	write_repository ; cela n’accorde pas d’accès général en écriture à l’API

Pour des builds en lecture seule, commencez par read_api + read_repository, et non par api. Le scope étendu api ne convient que lorsque vous activez les processus d’écriture qui en ont besoin. Les scopes de jeton ne peuvent pas passer outre les règles de branches protégées ou une appartenance au projet manquante. L’autorisation GitLab propre à chaque utilisateur pour les outils interactifs reste distincte du jeton système enregistré.

Références : Créer un personal access token GitLab, Scopes des jetons d’accès GitLab.

GitHub

Lorsque vous ajoutez un connecteur GitHub, Opfield demande comment l’autoriser. Pour GitHub.com, choisissez OAuth (Recommended) : Opfield affiche un code d’appareil, vous l’approuvez sur GitHub, et aucun jeton n’est copié dans Opfield. Il demande repo, workflow, read:org et read:packages ; examinez l’accès aux organisations et aux dépôts sur l’écran de consentement de GitHub. Pour GitHub Enterprise, ou pour utiliser un jeton, choisissez Personal access token :

1. Ouvrez dans GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic).
2. Définissez un nom dédié et une expiration. Sélectionnez repo pour les dépôts privés, ou public_repo si seuls des dépôts publics sont nécessaires. Ce sont des permissions étendues sur les dépôts, et non des scopes en lecture seule : utilisez une identité dont l’accès aux dépôts est restreint de manière appropriée.
3. N’ajoutez des permissions facultatives que pour le processus correspondant ci-dessous. Générez et copiez le jeton. Autorisez-le pour le SSO de l’organisation lorsque c’est nécessaire.
4. Ajoutez le jeton dans l’intégration GitHub d’Opfield, sélectionnez les dépôts et organisations autorisés, et testez la découverte des dépôts et la révision prévue.

Usage supplémentaire	Scope du jeton classique
Lire l’appartenance aux organisations et aux équipes	read:org
Télécharger des paquets depuis GitHub Packages	read:packages
Modifier les fichiers de workflow	workflow, en plus de l’accès aux dépôts

Limitation de compatibilité actuelle : Opfield détecte les capacités d’un jeton GitHub à partir des scopes OAuth classiques. Un PAT à granularité fine (fine-grained) peut s’authentifier auprès de GitHub, mais être tout de même signalé sans capacités sur les dépôts par ce connecteur. Ne l’utilisez pas comme remplacement direct de la recette ci-dessus. Si l’organisation interdit les PAT classiques, utilisez l’option OAuth ou résolvez la compatibilité du connecteur avant de vous connecter ; n’affaiblissez pas la politique de l’organisation. Aucun scope delete_repo ou d’administration de l’organisation n’est nécessaire pour construire un dépôt enregistré.

Références : Gérer les personal access tokens GitHub, Signification des scopes OAuth classiques.

Git générique

1. Sur le serveur Git, créez un identifiant dédié capable de cloner les dépôts sélectionnés. Par exemple, un deploy token GitLab avec read_repository peut être utilisé pour l’accès Git sur HTTPS ; ce n’est pas un jeton d’API GitLab de premier plan.
2. Dans Opfield, choisissez Git générique. Saisissez Git host URL, par exemple https://git.example.com, et les Repositories explicites, par exemple https://git.example.com/team/app.git.
3. Saisissez Username et Access token séparément. Pour un deploy token, utilisez le nom d’utilisateur émis avec ce jeton. N’intégrez aucune de ces valeurs dans les URL de dépôts.
4. Lancez Test Connection, puis enregistrez. Le test de connexion utilise le premier dépôt : vérifiez aussi l’accès à chacun des autres dépôts autorisés avant de vous appuyer dessus pour un build.

Ce connecteur utilise des identifiants HTTPS, et non une clé privée importée depuis External SSH. Il ne fournit ni vocabulaire universel de scopes de fournisseurs Git, ni l’ensemble complet des fonctionnalités de l’API GitLab ou GitHub. Un clonage réussi n’implique pas la permission de gérer des webhooks, des variables ou la CI via une API.

Configurer en toute sécurité

1. Créez une identité de fournisseur ou une identité machine dédiée.
2. Accordez un accès aux dépôts en lecture seule, sauf si un processus documenté nécessite des écritures.
3. Restreignez les organisations, groupes, projets et dépôts à l’aide du mode de sélection pris en charge par le connecteur.
4. Ajoutez l’intégration dans Settings → Integrations.
5. Vérifiez TLS ou l’identité SSH de l’hôte avant d’enregistrer les identifiants.
6. Testez la découverte des dépôts et l’accès à une révision autorisée.
7. Vérifiez qu’un dépôt ou un hôte hors périmètre est refusé.
8. Ne configurez l’authenticité et l’envoi des webhooks qu’une fois le chemin de lecture fonctionnel.

Restreindre l’accès aux dépôts

La liste d’autorisation du connecteur décide quels dépôts Opfield peut atteindre. Les scopes d’intégration Git décident quels utilisateurs, groupes, jetons d’API et autorisations OAuth peuvent les utiliser. Chaque scope Git, sauf manage, peut être limité en dessous du connecteur :

• GitLab : un groupe, qui couvre aussi ses sous-groupes et chaque projet qu’ils contiennent, ou un projet unique. Opfield lit auprès de GitLab les groupes parents d’un projet ; un projet déplacé dans un autre groupe suit donc son nouveau groupe.
• GitHub : un propriétaire, qui couvre chaque dépôt de cette organisation ou de cet utilisateur, ou un dépôt unique.
• Git générique : uniquement le connecteur.

L’administration du connecteur — paramètres, jetons, liste d’autorisation, synchronisation, test et suppression — nécessite integrations:<provider>:manage sur le connecteur ou sans restriction ; un droit sur un groupe, un propriétaire, un projet ou un dépôt ne le permet jamais.

Le moyen le plus rapide d’accorder un accès aux dépôts est Add Access > Git repositories dans la boîte de dialogue de groupe, les permissions supplémentaires d’un utilisateur ou la boîte de dialogue des jetons d’API : choisissez le connecteur, Every repository ou un groupe, un propriétaire ou des dépôts individuels, et le niveau d’accès (Use, Read code ou Edit code and CI), qui définit les scopes correspondants. Pour restreindre un seul scope, ouvrez sa restriction sous Review N scopes dans ces boîtes de dialogue ou dans le consentement OAuth et MCP. Cochez un connecteur pour couvrir tous ses dépôts, ou ouvrez Add groups or projects… ou Add owners or repositories… sous le connecteur pour rechercher chez le fournisseur et sélectionner des cibles. Les droits stockent les identifiants numériques du fournisseur ; les renommages et déplacements ne les cassent donc pas ; une cible supprimée depuis est affichée comme Unavailable et peut toujours être retirée.

Avec des droits restreints :

• Les listes de connecteurs, de projets et de dépôts, y compris le sélecteur de source de build, n’affichent que ce que couvrent les droits. Un projet absent d’une liste est généralement hors du droit plutôt que non synchronisé.
• Chaque opération sur un dépôt vérifie le dépôt — fichiers, branches, commits, pipelines et journaux des jobs, variables, webhooks, deploy tokens, paramètres du registre et clones en bac à sable —, dans la Console, l’API REST, AI Workspace et MCP de la même manière. Un projet GitLab hors du droit répond exactement comme un projet non synchronisé : 404 GITLAB_PROJECT_NOT_FOUND, sans son chemin, de sorte que les identifiants de projets ne peuvent pas être sondés. Pour GitHub et Git générique, où l’appelant fournit déjà le dépôt, un refus renvoie 403 CONNECTOR_SCOPE_DENIED avec le scope requis.
• Opfield n’utilise l’identifiant du connecteur pour un dépôt que lorsque use couvre ce dépôt ; sinon, il utilise l’identifiant personnel de l’utilisateur.
• Les écritures, les secrets, les clones en bac à sable et la décision relative à l’identifiant lisent à neuf auprès du fournisseur les groupes d’un projet GitLab ou le propriétaire d’un dépôt GitHub ; un dépôt transféré est donc jugé selon son emplacement actuel ; les simples lectures peuvent utiliser une valeur mise en cache jusqu’à cinq minutes. Les synchronisations de connecteurs et les livraisons de webhooks de sources vident le cache.
• Le sélecteur de recherche ne propose que des cibles incluses dans la liste d’autorisation du connecteur et est limité à 60 requêtes par minute et par compte ; au-delà, il renvoie 429 SCOPE_TARGET_RATE_LIMITED avec Retry-After.
• Les jetons d’API et les autorisations OAuth conservent leurs propres restrictions et sont aussi vérifiés par rapport aux droits actuels du propriétaire à chaque requête. Un jeton restreint à un projet fonctionne tant que son propriétaire détient le groupe qui contient le projet et cesse de fonctionner lorsque le propriétaire perd cet accès.

Voir Restrictions de l’intégration Git pour le format exact des qualificatifs et les points de terminaison du sélecteur.

Cycle de vie des liaisons de sources

Qui peut lancer des builds et consulter les résultats ?

La découverte des dépôts et les opérations directes sur les sources utilisent les scopes d’intégration des fournisseurs. GitLab, GitHub et Git générique partagent les mêmes verbes : integrations:<provider>:view liste les connecteurs, :manage les configure, les teste et les synchronise, :use utilise l’identifiant propre au connecteur, et :repo:read et :repo:write lisent ou modifient le contenu des dépôts. Lister et lire les projets synchronisés de GitLab nécessite integrations:gitlab:view. repo:read de GitLab couvre les fichiers des dépôts, les pipelines CI et les journaux des jobs, ainsi que les clés des variables CI/CD, jamais leurs valeurs ; modifier les variables nécessite repo:write, et lire les valeurs des variables GitHub Actions nécessite integrations:github:repo:write. Les groupes intégrés viewer et operator ne reçoivent que integrations:gitlab:view. Voir la référence des scopes. Chacun de ces scopes peut être limité à un connecteur, à un groupe ou projet GitLab, ou à un propriétaire ou dépôt GitHub ; voir Restreindre l’accès aux dépôts.

Rattacher ou modifier une liaison de source nécessite integrations:<provider>:use sur le dépôt, en plus des permissions propres à la charge de travail. use limité à ce seul projet ou dépôt suffit ; repo:read et un identifiant personnel auprès du fournisseur ne sont pas nécessaires, car les builds utilisent l’identifiant du connecteur. Le groupe intégré operator peut donc voir les projets GitLab dans le sélecteur de source, mais ne peut pas enregistrer de source tant que integrations:gitlab:use ne lui est pas accordé, de préférence limité aux projets qu’il construit. Les outils GitLab interactifs d’AI Workspace demandent l’autorisation GitLab propre à l’utilisateur lorsque use ne couvre pas le projet.

Lancer un build depuis une source déjà enregistrée est une action sur la ressource — docker:containers:manage pour les conteneurs et Deployments, docker:compose:manage pour Compose et pages:deploy pour Pages — qui revérifie aussi l’integrations:<provider>:use de l’appelant sur le dépôt enregistré ; révoquer use arrête donc les reconstructions manuelles. repo:read n’est toujours pas nécessaire. Opfield vérifie aussi le connecteur enregistré, le dépôt autorisé et les identifiants de la source.

Les builds automatiques déclenchés par interrogation périodique et par webhook dépendent du moment où la source a été enregistrée pour la dernière fois :

• Les sources enregistrées avant 2.11 continuent de construire automatiquement exactement comme avant.
• Les sources créées ou enregistrées à nouveau depuis ne construisent automatiquement que tant que le compte qui les a enregistrées en dernier détient toujours integrations:<provider>:use sur le dépôt et reste actif. Sinon, aucun build ne s’exécute : l’historique des builds affiche un build annulé avec SOURCE_OWNER_ACCESS_REVOKED et le message Build paused: <user> no longer has use on <repo>, enregistré une fois par commit, et la source affiche le même message comme erreur d’interrogation ou de webhook. Les livraisons de webhooks restent acceptées. Les builds automatiques reprennent lorsque le compte récupère use, ou lorsqu’une personne qui le détient enregistre à nouveau la source.

Accordez use aux équipes qui enregistrent des sources, limité à leurs projets, avant de vous appuyer sur les builds automatiques.

L’historique et les journaux des builds nécessitent un droit de consultation sur la cible : docker:containers:view, docker:compose:view ou pages:view. Les restrictions par ressource et par dossier hérité s’appliquent. Depuis 2.11, tout scope d’action sur la même cible, comme docker:containers:manage, accorde aussi la consultation de celle-ci. N’accordez pas d’accès aux dépôts ou aux nœuds à l’échelle du compte pour contourner un droit manquant sur la cible. Voir Permissions.

Liaisons de sources enregistrées

Les charges de travail Docker, les projets Compose et les projets Pages créent leurs propres liaisons de sources. Une liaison de source enregistre l’intégration, le dépôt, la sélection de révision, la configuration du build, la politique d’automatisation et les Build Secrets limités à la source.

Retirer une intégration ne rend pas sûre la reconstruction des ressources dépendantes. Inventoriez d’abord les dépendances, désactivez les actions automatiques, migrez chaque liaison de source et vérifiez la révision et les identifiants de remplacement.

Poursuivez avec Builds Git Docker, Déploiements Git de Pages et Registres de conteneurs. Pour les autres types de connecteurs, revenez aux Intégrations.

Dépannage

Distinguez les échecs d’authentification, les refus de la liste d’autorisation, les dépôts introuvables, la résolution des révisions, l’envoi des webhooks, l’admission sur le Build Worker et les échecs liés aux droits. Conservez les identifiants de requêtes du fournisseur et l’historique des tâches d’Opfield sans journaliser de jetons, de clés privées, de variables ou de Build Secrets.

Processus de source en production

Épinglez la source de production sur une politique de branche revue et un commit résolu exact. Un nom de branche est une entrée de sélection ; l’empreinte du commit est la preuve immuable de ce qui a été construit. Confirmez la racine de l’application, le gestionnaire de paquets, le script de build, le répertoire de l’artefact, la plateforme d’exécution et la politique de publication ou de déploiement avant d’activer les actions automatiques. Gardez les Build Secrets séparés des variables d’exécution ordinaires et n’exposez que les valeurs nécessaires à l’étape de build.

Pour Pages et les builds Git gérés, vérifiez la chaîne complète : accès au fournisseur, découverte des dépôts, résolution du commit, admission sur le Build Worker, récupération des dépendances, création de l’artefact, politique de vulnérabilités lorsqu’elle est activée, identité immuable de l’artefact, tag de publication ou révision de la charge de travail, et santé visible par les clients. Un webhook de fournisseur ou un clonage de source réussi n’est que le début de cette chaîne.

Expiration et rotation des jetons

Opfield enregistre la date d’expiration des jetons des connecteurs GitLab et des jetons GitLab personnels des utilisateurs, et les vérifie chaque jour.

• Alertes : Opfield alerte 30 et 7 jours avant l’expiration d’un jeton de connecteur, d’un jeton GitLab personnel ou de l’autorisation d’une intégration connectée par OAuth, chaque fois que l’expiration est connue. GitLab signale l’expiration de ses jetons ; les jetons GitHub et Git générique sont couverts lorsqu’ils sont connectés via OAuth.
• Rotation automatique GitLab : 14 jours avant l’expiration, Opfield fait tourner les jetons des connecteurs GitLab et les jetons GitLab personnels qui disposent du scope api ou self_rotate. Le nouveau jeton conserve la durée de vie précédente, entre 30 jours et un an, et remplace le secret stocké ; la rotation est auditée. Les jetons d’accès de projet et de groupe ne peuvent pas se faire tourner eux-mêmes par ce chemin et ne reçoivent que des alertes.
• Jetons expirés : Opfield cesse d’utiliser un jeton une fois expiré. Un jeton GitLab personnel expiré échoue avec GIT_CREDENTIAL_EXPIRED (HTTP 428) ; l’utilisateur doit donc en autoriser un nouveau ; un jeton de connecteur GitLab expiré échoue avec CONNECTOR_TOKEN_EXPIRED (HTTP 409). Remplacer un jeton de connecteur expiré ne nécessite pas l’ancien.

Les synchronisations, les sources Docker et les builds Pages qui dépendent d’un jeton expiré cessent de fonctionner jusqu’à son remplacement ; considérez donc l’alerte à 30 jours comme l’échéance de rotation des jetons qu’Opfield ne peut pas faire tourner lui-même.

Rotation, migration et suppression

Pour faire tourner des identifiants, ajoutez le remplaçant chez le fournisseur et dans Opfield, vérifiez la découverte et un vrai build, puis révoquez la valeur précédente. Pour changer de fournisseur ou de dépôt, gelez les déploiements automatiques, consignez le dernier commit approuvé et l’empreinte de l’artefact, configurez la source de remplacement, comparez l’arborescence résolue, lancez un build canari, et ne déplacez explicitement le pointeur de production qu’après vérification.

Avant de supprimer un connecteur, listez chaque dépendance Docker, Compose, Pages, de registre, de webhook et d’automatisation. Désactivez d’abord les déclencheurs. Les artefacts immuables existants peuvent continuer à s’exécuter, mais les builds futurs, les actualisations ou la reprise à partir de la source peuvent échouer après la disparition du connecteur. Conservez le dernier artefact approuvé et les instructions de retour arrière jusqu’à ce que le nouveau chemin de source ait traversé un cycle d’exploitation.

Revue de sécurité

Examinez les journaux d’audit du fournisseur, les permissions des applications installées, les clés de déploiement, les clés d’hôte SSH, les secrets des webhooks, les organisations et dépôts autorisés, ainsi que les liaisons inactives. Un accès en lecture aux dépôts peut exposer du code source et une configuration propriétaires ; les permissions d’écriture ou de workflow peuvent affecter la chaîne d’approvisionnement logicielle. Ne les accordez que lorsque le processus Opfield choisi l’exige.

La revue des dépôts, les branches protégées, la politique de dépendances et l’approbation des artefacts restent dans votre fournisseur Git et votre processus de revue. Opfield construit et déploie par-dessus, avec des scopes et un audit, et suit votre politique de sources au lieu de la contourner.