GitHub
Comment BernOps se connecte aux repositories GitHub, quelles permissions sont requises et comment les exports restent revus.
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.
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.
- Un utilisateur BernOps connecte avec acces admin au projet appelle
POST /api/projects/{projectId}/github/install-url. - 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. - Le navigateur est redirige vers l'URL d'autorisation OAuth de la GitHub App avec cet etat signe.
- GitHub redirige vers
GET /api/github/setupavec uncodeOAuth. - 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.
- GitHub redirige vers
GET /api/github/setupavec uninstallation_id. - 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.
- 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.
- 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 App | Acces | Pourquoi BernOps en a besoin |
|---|---|---|
| Metadata | Read-only | Identifier les installations et repositories exposes par l'installation. |
| Contents | Read and write | Lire les arbres et contenus du repository, puis creer des Git trees, commits et refs de branche pour les branches d'export BernOps. |
| Pull requests | Read and write | Ouvrir 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.
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 :
InstallationInstallation repositoriesPull request- Observation CI optionnelle :
Workflow jobetCheck 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 :
| Evenement | Actions traitees par BernOps |
|---|---|
installation | Supprime les installations locales quand GitHub supprime l'installation, et marque les installations comme suspendues ou non suspendues quand GitHub envoie ces actions. |
installation_repositories | Deconnecte les repositories BernOps quand un repository est retire de l'installation GitHub App. |
pull_request | Met 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_job | Taches Actions des projets actives : en file/en cours/terminees ; identites distinctes par variante/tentative. |
check_run | Fournisseurs, sans sorties/journaux. Doublons Actions ignores (workflow_job). |
| Autres evenements | Ignores 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 identifiant | Utilisation | Traitement par BernOps |
|---|---|---|
| Cle privee App | Backend | GITHUB_APP_PRIVATE_KEY signe les JWT courts RS256. |
| JWT d'app | GitHub | Identifie l'installation et obtient son token. |
| Token d'installation | GitHub | Liste/lecture/ecriture autorisees ; cache memoire rafraichi, jamais en base. |
| Token OAuth utilisateur | GitHub | Verifie l'acces de l'installateur ; chiffre temporairement dans github_setup_states, puis efface. |
| Secret webhook | Backend | GITHUB_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 :
| Donnee | Champs stockes |
|---|---|
| Installation | Workspace/ID GitHub, compte/type, selection, permissions, installateur, suspension/dates. |
| Repository | Projet/installation/ID GitHub, owner/nom, branche, dossier, connecteur/dates. |
| PR d'export | Repository, branches/SHA, numero/URL, statut/draft, erreur, createur/dates. |
| Livraison webhook | ID, evenement/action, installation/repository, statut/erreur, dates. |
| Configuration | Nonce, projet/workspace/utilisateur, expiration/consommation, token chiffre temporaire/date OAuth. |
| Observation CI | Projet/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 :
- Charger le repository connecte et l'installation.
- 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.
- Charger les jobs geres par BernOps pour le projet.
- Construire les chemins cible en joignant le dossier d'export configure avec le nom de fichier de chaque job.
- Resoudre le SHA courant de la branche de base et lire les fichiers existants depuis ce commit exact pour detecter les conflits.
- 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.
- Ouvrir une nouvelle pull request en brouillon ou mettre a jour la pull request BernOps ouverte et suivie.
- 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.
| Situation | Resultat |
|---|---|
| Le fichier cible existe deja mais le job BernOps n'a pas de SHA de blob GitHub deja enregistre | Ignore avec remote file already exists and has not been exported by BernOps. |
| Le fichier cible a change dans GitHub depuis le dernier export BernOps | Ignore avec remote file changed since the last BernOps export. |
| Le fichier cible a ete supprime apres un export BernOps precedent | Ignore avec remote file was removed since the last BernOps export. |
| Le code du job est vide | Ignore et marque comme erreur. |
| Deux jobs resolvent le meme chemin d'export | Le doublon suivant est ignore et marque comme erreur. |
| La branche d'export BernOps existante a bouge de maniere inattendue | L'export echoue avec un conflit et demande de reessayer apres rafraichissement de l'etat PR. |
| La branche par defaut bouge pendant un export initial | L'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 BernOps | Acces BernOps requis |
|---|---|
| Lire l'etat de connexion | Acces projet. |
| Lire l'arborescence du repository selectionne | Acces projet. |
| Lire les pull requests d'export suivies | Acces projet. |
| Creer l'URL d'installation GitHub | Acces proprietaire/admin espace. |
| Lister les repositories d'installation pour selection | Acces admin projet. |
| Selectionner ou remplacer la connexion repository | Acces admin projet. |
| Deconnecter le repository | Acces admin projet. |
| Exporter les tests vers GitHub | Acces 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 :
- Choosing permissions for a GitHub App
- About authentication with a GitHub App
- Using webhooks with GitHub Apps
- Validating webhook deliveries
- Git trees REST API
- Git commits REST API
- Git references REST API
- Repository contents REST API
- Pull requests REST API
Pour les chemins REST BernOps exacts et les formes de reponse, ouvrez la Reference API et cherchez GitHub.