Documentation
Documentation/Integrations

GitHub

Comment BernOps se connecte aux repositories GitHub, quelles permissions sont requises et comment les exports restent revus.

githubrepositories gitpermissionswebhookspull requests
Voir le Markdown
Sur cette page

Un projet BernOps se connecte a un repository expose par une GitHub App : lecture de l'arborescence, export des jobs Playwright en PR brouillon et observation CI optionnelle.

Portee actuelle

BernOps connecte un seul repository par projet. BernOps ne clone pas le repository, n'execute pas le code du repository, ne merge pas les pull requests, ne modifie pas les parametres du repository, ne gere pas les secrets GitHub et n'ecrit pas directement sur la branche par defaut.

Ce que fait l'integration

La GitHub App permet de :

  • Choisir un repository expose et stocker identite, branche par defaut et dossier d'export.
  • Lire l'arborescence et les fichiers d'export pour proteger les fichiers externes.
  • Creer une branche bernops/update-tests-20260503121000-ab12cd34, y committer les jobs (Update BernOps tests), ouvrir/mettre a jour une PR brouillon du meme titre.
  • Suivre la PR par webhook et actualiser la synchronisation des jobs.

BernOps exporte uniquement les jobs enregistres dont les metadonnees indiquent source_kind = bernops et managed_by = platform. L'endpoint d'export n'exporte pas de fichiers arbitraires du repository.

Flux de configuration

L'installation commence dans BernOps, pas directement depuis les parametres de la GitHub App. L'URL d'installation generee par BernOps transporte un etat signe qui lie le flux GitHub a un projet, un workspace, un utilisateur et un nonce BernOps.

  1. Un utilisateur BernOps connecte avec acces admin au projet appelle POST /api/projects/{projectId}/github/install-url.
  2. Le backend cree un nonce de configuration aleatoire, le stocke dans github_setup_states, signe un payload d'etat avec HMAC-SHA256 et fixe une expiration de 10 minutes.
  3. Le navigateur est redirige vers l'URL d'autorisation OAuth de la GitHub App avec cet etat signe.
  4. GitHub redirige vers GET /api/github/setup avec un code OAuth.
  5. Le backend echange le code contre un token utilisateur GitHub, chiffre ce token avec AES-GCM et une cle backend independante, le stocke temporairement sur la ligne d'etat de configuration, puis redirige vers l'URL d'installation de la GitHub App avec le meme etat signe.
  6. GitHub redirige vers GET /api/github/setup avec un installation_id.
  7. Le backend verifie l'etat signe, charge la ligne d'etat non consommee, dechiffre le token utilisateur temporaire et appelle GitHub pour verifier que l'utilisateur GitHub ayant autorise le flux peut acceder a l'installation retournee.
  8. Le backend recupere les metadonnees d'installation depuis GitHub et finalise la configuration via une RPC base de donnees service-role qui consomme l'etat et upsert l'installation de maniere atomique.
  9. Le token utilisateur GitHub chiffre est efface lorsque la configuration est finalisee. Les lignes de configuration expirees ont aussi leur token temporaire efface par le worker de retention.

Si l'etat signe est manquant, expire, reutilise ou ne correspond pas au projet, workspace et utilisateur stockes, la configuration est rejetee et l'utilisateur est redirige vers une page de resultat de configuration GitHub.

Permissions GitHub requises

Les permissions GitHub App ci-dessous limitent les APIs et webhooks accessibles. Gardez le minimum requis.

Permission GitHub AppAccesPourquoi BernOps en a besoin
MetadataRead-onlyIdentifier les installations et repositories exposes par l'installation.
ContentsRead and writeLire les arbres et contenus du repository, puis creer des Git trees, commits et refs de branche pour les branches d'export BernOps.
Pull requestsRead and writeOuvrir ou mettre a jour des pull requests en brouillon et traiter les changements d'etat de pull request.

CI optionnelle : Actions/Checks en lecture, evenements workflow_job/check_run, configures par le proprietaire App et approuves par l'installation. Aucun droit d'organisation ou d'ecriture supplementaire.

Utilisez les repositories selectionnes quand c'est possible

L'installation peut exposer tous les repositories ou une selection. Le projet n'en connecte qu'un ; limitez aussi l'installation aux seuls repositories necessaires.

Evenements webhook

La GitHub App doit souscrire a ces evenements :

  • Installation
  • Installation repositories
  • Pull request
  • Observation CI optionnelle : Workflow job et Check run (permissions de lecture ci-dessus).

ping automatique est accepte puis ignore. Un echec de traitement est enregistre et retourne non-2xx pour permettre une nouvelle livraison GitHub.

BernOps traite les evenements souscrits ainsi :

EvenementActions traitees par BernOps
installationSupprime les installations locales quand GitHub supprime l'installation, et marque les installations comme suspendues ou non suspendues quand GitHub envoie ces actions.
installation_repositoriesDeconnecte les repositories BernOps quand un repository est retire de l'installation GitHub App.
pull_requestMet a jour les pull requests d'export BernOps suivies, marque les jobs synced quand une PR suivie est mergee, et remet les metadonnees des jobs pending a not_synced quand une PR suivie est fermee sans merge.
workflow_jobTaches Actions des projets actives : en file/en cours/terminees ; identites distinctes par variante/tentative.
check_runFournisseurs, sans sorties/journaux. Doublons Actions ignores (workflow_job).
Autres evenementsIgnores apres verification de signature et enregistrement de la livraison.

Observation CI

Apres deploiement/configuration GitHub App, l'admin active Verifications CI sur la page GitHub du projet. Desactive par defaut ; nouveaux webhooks signes, aucun replay ni cle dans les PR.

  • GET /api/projects/{projectId}/github/checks : acces projet ; enabled, repository_id, 100 observations.
  • Admin : PATCH /api/projects/{projectId}/github/checks/settings, {"enabled":true} ou {"enabled":false} ; permissions GitHub inchangees.
  • Installation/repository/projet/workspace verifies atomiquement ; connexion suspendue/desactivee refusee.
  • Etats natifs distincts, dont annule/ignore/neutre ; conflits ambigus, absence inconnue. Metadonnees bornees seulement : aucun journal, sortie brute, execution ou relance.

Fournisseurs selon check_run disponible, status classique exclu. Detail d'etape : SDK. GitHub fait autorite pour l'annulation et le nettoyage post-tache.

Auth et gestion des tokens

Trois identifiants distincts : JWT d'app, token d'installation, token utilisateur.

Token ou identifiantUtilisationTraitement par BernOps
Cle privee AppBackendGITHUB_APP_PRIVATE_KEY signe les JWT courts RS256.
JWT d'appGitHubIdentifie l'installation et obtient son token.
Token d'installationGitHubListe/lecture/ecriture autorisees ; cache memoire rafraichi, jamais en base.
Token OAuth utilisateurGitHubVerifie l'acces de l'installateur ; chiffre temporairement dans github_setup_states, puis efface.
Secret webhookBackendGITHUB_WEBHOOK_SECRET verifie les signatures ; etat et chiffrement utilisent des secrets independants.

Configuration App manquante : operations GitHub 503. Lire les observations stockees n'appelle pas GitHub.

Donnees stockees par BernOps

Metadonnees de connexion et d'export :

DonneeChamps stockes
InstallationWorkspace/ID GitHub, compte/type, selection, permissions, installateur, suspension/dates.
RepositoryProjet/installation/ID GitHub, owner/nom, branche, dossier, connecteur/dates.
PR d'exportRepository, branches/SHA, numero/URL, statut/draft, erreur, createur/dates.
Livraison webhookID, evenement/action, installation/repository, statut/erreur, dates.
ConfigurationNonce, projet/workspace/utilisateur, expiration/consommation, token chiffre temporaire/date OAuth.
Observation CIProjet/repository, ID fournisseur/tentative, etat/conclusion, commit/lien, dates/conflit.

github_webhook_deliveries ne stocke aucun corps brut : metadonnees/statut seulement, pour deduplication, reprises et audit.

Comportement d'export

Quand un admin projet exporte les tests vers GitHub, BernOps n'ecrit pas sur la branche par defaut. BernOps cree ou met a jour une branche BernOps et ouvre ou met a jour une pull request en brouillon.

Le pipeline d'export est :

  1. Charger le repository connecte et l'installation.
  2. Acquerir un verrou d'export au niveau du repository pendant au plus 30 minutes pour que deux requetes d'export ne puissent pas ecrire des branches GitHub concurrentes en meme temps.
  3. Charger les jobs geres par BernOps pour le projet.
  4. Construire les chemins cible en joignant le dossier d'export configure avec le nom de fichier de chaque job.
  5. Resoudre le SHA courant de la branche de base et lire les fichiers existants depuis ce commit exact pour detecter les conflits.
  6. Creer un Git tree, un commit et une ref de branche via les APIs GitHub Git, en echouant si la branche de base bouge apres la verification de conflits.
  7. Ouvrir une nouvelle pull request en brouillon ou mettre a jour la pull request BernOps ouverte et suivie.
  8. Rafraichir les metadonnees de fichiers depuis GitHub et marquer les jobs exportes comme pending_pr.

Le dossier d'export par defaut est bernops/e2e. Un dossier personnalise est accepte seulement s'il est un chemin relatif sur. Les chemins absolus, backslashes, .. et chemins qui sortent du dossier du repository apres nettoyage sont rejetes.

Protection contre les conflits

BernOps ignore les fichiers au lieu d'ecraser du contenu repository qu'il ne peut pas prouver posseder.

SituationResultat
Le fichier cible existe deja mais le job BernOps n'a pas de SHA de blob GitHub deja enregistreIgnore avec remote file already exists and has not been exported by BernOps.
Le fichier cible a change dans GitHub depuis le dernier export BernOpsIgnore avec remote file changed since the last BernOps export.
Le fichier cible a ete supprime apres un export BernOps precedentIgnore avec remote file was removed since the last BernOps export.
Le code du job est videIgnore et marque comme erreur.
Deux jobs resolvent le meme chemin d'exportLe doublon suivant est ignore et marque comme erreur.
La branche d'export BernOps existante a bouge de maniere inattendueL'export echoue avec un conflit et demande de reessayer apres rafraichissement de l'etat PR.
La branche par defaut bouge pendant un export initialL'export echoue au lieu d'ecrire des fichiers qui n'ont pas ete verifies contre les conflits.

Quand BernOps met a jour une branche d'export existante, le backend transmet le SHA head precedemment suivi et met a jour la ref Git avec force = false. Cela evite d'ecraser silencieusement du travail ajoute a la branche d'export en dehors de BernOps.

Controle d'acces BernOps

BernOps protege les actions de gestion GitHub avec les memes controles de role projet que le reste de l'app.

Action BernOpsAcces BernOps requis
Lire l'etat de connexionAcces projet.
Lire l'arborescence du repository selectionneAcces projet.
Lire les pull requests d'export suiviesAcces projet.
Creer l'URL d'installation GitHubAcces proprietaire/admin espace.
Lister les repositories d'installation pour selectionAcces admin projet.
Selectionner ou remplacer la connexion repositoryAcces admin projet.
Deconnecter le repositoryAcces admin projet.
Exporter les tests vers GitHubAcces admin projet.

Les endpoints de configuration GitHub et de webhook sont des routes HTTP sans authentification utilisateur parce que GitHub les appelle directement. Ils ne sont pas des frontieres de confiance ouvertes : la configuration exige un etat signe et une validation du nonce stocke, et les webhooks exigent que la signature HMAC X-Hub-Signature-256 de GitHub corresponde au secret webhook configure.

Deconnexion et desinstallation

Deconnecter un repository dans BernOps supprime la connexion repository selectionnee pour le projet. L'installation GitHub App reste disponible au workspace, donc un admin projet peut reconnecter ce projet ou connecter un autre projet plus tard.

Quand une connexion repository est supprimee ou remplacee, BernOps efface les observations CI et remet a zero la synchronisation GitHub des jobs lies. Nouvel opt-in requis, meme pour un changement de dossier. Si un verrou d'export est actif, les mutations de connexion et de deconnexion retournent un conflit au lieu de changer la connexion pendant que des ecritures GitHub sont en cours.

Si l'installation GitHub App est supprimee dans GitHub, le webhook installation fait supprimer la ligne d'installation locale dans BernOps. Comme les connexions repository referencent les installations avec ON DELETE CASCADE, les connexions repository de cette installation sont aussi supprimees.

Ce que BernOps ne fait pas

Ces affirmations refletent les chemins de code actuels de l'integration GitHub :

  • BernOps ne merge pas les pull requests GitHub.
  • BernOps n'ecrit pas directement sur la branche par defaut du repository.
  • BernOps ne force-update pas les refs Git.
  • BernOps ne demande pas de permissions d'organisation GitHub pour cette integration.
  • BernOps n'utilise pas les APIs GitHub Actions, Secrets, Administration, Deployments, Packages, Members, Issues, Checks ou Workflows dans l'integration actuelle.
  • BernOps ne stocke pas les tokens d'installation en base de donnees.
  • BernOps ne conserve pas le token OAuth utilisateur de configuration apres finalisation de la configuration.
  • BernOps ne stocke pas les corps bruts des payloads webhook GitHub dans la table des livraisons webhook.
  • BernOps ne clone pas le repository connecte et n'execute pas son code pendant la connexion ou l'export.

References officielles

Documentation GitHub pour les comportements de plateforme pertinents :

Pour les chemins REST BernOps exacts et les formes de reponse, ouvrez la Reference API et cherchez GitHub.