Antoine Laurent

Posted on Jun 9 • Originally published at apidog.com

Bruno pour les équipes : Alternatives et astuces de synchronisation cloud

En bref

Bruno ne propose pas de synchronisation cloud intégrée. En pratique, les équipes partagent leurs collections via Git, un lecteur réseau ou un conteneur de développement. Ces approches fonctionnent, mais elles ont des limites : pas de collaboration en temps réel, gestion manuelle des secrets, conflits Git et permissions peu adaptées. Apidog couvre maintenant les deux besoins : le mode Git Spec-First garde votre spécification OpenAPI dans votre dépôt et dans vos pull requests, tandis que la synchronisation cloud optionnelle ajoute collaboration temps réel, RBAC, identifiants centralisés et mock server intégré.

Essayez Apidog aujourd’hui

Introduction

Bruno est conçu pour être local-first. Vos collections restent sur votre machine, sans compte cloud ni abonnement. C’est un choix cohérent pour les développeurs qui veulent garder le contrôle de leurs fichiers.

Le problème apparaît dès qu’une équipe doit travailler sur les mêmes requêtes :

comment partager une collection API entre 5 développeurs ?
comment un QA récupère-t-il la dernière version des requêtes ?
comment intégrer un nouvel arrivant sans lui envoyer des fichiers par Slack ?
comment éviter que chaque développeur ait sa propre version divergente ?

Ce guide détaille les solutions utilisées avec Bruno, leurs limites concrètes et le cas où le mode Git Spec-First d’Apidog devient plus adapté. Pour une vue d’ensemble, consultez aussi ce comparatif des outils API compatibles avec Git.

1. Utiliser Git avec Bruno

Bruno a été pensé pour Git. Les collections sont stockées dans des fichiers .bru, les environnements dans des fichiers JSON, et l’ensemble reste lisible en texte brut.

Mise en place

Créez un dépôt Git dédié, ou un dossier api-collections/ dans votre dépôt applicatif.
Ajoutez vos fichiers Bruno.
Poussez le dépôt vers GitHub, GitLab ou Bitbucket.
Chaque membre clone le dépôt.
Chacun ouvre le dossier dans Bruno.
Les changements passent par commit, push, puis pull.

Exemple de structure :

api-collections/
  bruno.json
  environments/
    local.json
    staging.json
    production.json
  users-api/
    get-user.bru
    create-user.bru
  orders-api/
    create-order.bru
    list-orders.bru

Avantages

Historique complet des modifications.
Revue de code possible sur les requêtes.
Intégration CI/CD naturelle avec bru run.
Pas de service tiers en dehors de votre hébergeur Git.
Fonctionne bien avec une équipe de développeurs à l’aise avec Git.

Limites

Les profils non développeurs doivent apprendre Git.
Les changements ne sont pas visibles en temps réel.
Les secrets ne doivent pas être commités, donc il faut un mécanisme séparé.
Deux personnes modifiant la même requête peuvent créer des conflits.
Les permissions Git restent au niveau dépôt : pas de rôle “lecture seule” propre à une collection.

Cette approche convient surtout aux petites équipes de développeurs qui utilisent déjà Git pour tout. Elle s’inscrit dans une logique plus large de gestion de version OpenAPI avec Git.

2. Utiliser un lecteur réseau partagé

Certaines équipes placent le dossier Bruno sur un NAS, un partage réseau, Dropbox ou Google Drive.

Mise en place

Bruno peut ouvrir une collection depuis n’importe quel chemin local. Il suffit donc de pointer Bruno vers le dossier partagé.

/shared-drive/
  bruno/
    users-api/
    orders-api/
    environments/

Avantages

Installation rapide.
Pas besoin de Git.
Accessible aux non-développeurs.
Tous les membres voient les mêmes fichiers.

Limites

Pas de vrai historique de version.
Risque d’écrasement si deux personnes éditent en même temps.
Performances plus faibles sur de grandes collections.
Permissions limitées au système de fichiers.
Secrets toujours à gérer séparément.
Peu fiable hors ligne ou avec une connexion instable.

Cette option peut dépanner une équipe de 2 ou 3 personnes, mais elle devient fragile dès que plusieurs personnes modifient les collections régulièrement.

3. Utiliser Gitpod ou un conteneur de développement

Certaines équipes incluent leurs collections Bruno dans un environnement Gitpod ou dans un dev container.

Mise en place

La collection reste dans le dépôt. Le conteneur démarre avec Bruno, ou plus souvent avec la CLI Bruno, et la collection est déjà disponible.

Exemple simplifié :

repo/
  .devcontainer/
    devcontainer.json
  api-collections/
    bruno.json
    users-api/

Avantages

Environnement cohérent pour tous les développeurs.
La collection correspond à la version du code testée.
Moins de configuration locale.
Pratique pour exécuter des tests API dans l’environnement de développement.

Limites

Le workflow reste basé sur Git.
Les utilisateurs non-Git n’y gagnent pas grand-chose.
L’interface graphique de Bruno est difficile à utiliser dans la plupart des environnements cloud.
Pas de synchronisation temps réel.

Cette option est utile si votre équipe utilise déjà Gitpod ou des dev containers et souhaite intégrer les tests API dans l’environnement de développement.

4. Utiliser une copie par développeur

C’est le modèle le moins structuré : chaque développeur garde sa propre collection Bruno et la met à jour manuellement à partir d’exports ou de documents partagés.

Avantages

Aucun processus à mettre en place.
Rapide pour un développeur seul.
Autonomie complète.

Limites

Les collections divergent immédiatement.
Il n’y a plus de source de vérité.
Les corrections doivent être recopiées à la main.
La dette de maintenance augmente vite.

Cette approche ne convient pas à une équipe. Elle peut fonctionner uniquement pour un développeur solo ou un prototype.

Les limites communes de ces contournements

Même avec Git, les solutions de synchronisation autour de Bruno partagent quatre limites importantes.

1. Pas de collaboration en temps réel

Avec Bruno + Git, Alice doit push, puis Bob doit pull. Pendant une session de conception ou de test API, ce délai devient vite pénible.

Dans un outil collaboratif comme Apidog, plusieurs personnes peuvent travailler dans le même espace et voir les changements immédiatement.

2. Pas de contrôle d’accès basé sur les rôles

Git donne généralement accès en lecture ou en écriture au dépôt. Ce n’est pas la même chose qu’un modèle de rôles API.

Vous ne pouvez pas facilement définir :

un stakeholder qui peut exécuter des requêtes sans les modifier ;
un QA qui accède uniquement à certains projets ;
un contractuel limité à un dossier spécifique.

3. Pas d’identifiants partagés centralisés

Bruno évite à juste titre de commiter les secrets. Mais cela implique que chaque membre configure ses tokens localement.

Lorsqu’un token change, il faut prévenir tout le monde et vérifier que chaque environnement local est mis à jour.

4. Pas de commentaires au niveau collection

Les commentaires Git existent, mais ils sont attachés à une pull request ou à un diff. Ils ne vivent pas directement dans la collection ouverte par l’équipe.

Ces limites expliquent pourquoi certaines équipes finissent par chercher un outil plus collaboratif, sans pour autant abandonner Git.

Le mode Git Spec-First d’Apidog

Le choix habituel est souvent présenté ainsi :

Bruno + Git pour garder les fichiers dans le dépôt ;
ou un outil cloud pour collaborer.

Le mode Git Spec-First d’Apidog évite cette opposition. La spécification OpenAPI reste dans votre dépôt GitHub, GitLab ou auto-hébergé, et Apidog ajoute une couche de collaboration au-dessus.

Ce qui change par rapport à Bruno + Git

La spécification OpenAPI devient la source de vérité

Vous connectez un projet Apidog à un dépôt Git. La définition API est synchronisée sous forme de fichiers.

Workflow typique :

Créer une branche.
Modifier la spécification API.
Ouvrir une pull request.
Relire le diff du contrat API.
Fusionner.
Synchroniser l’espace Apidog.

Ce modèle reprend le flux de revue Git, mais l’applique à une spécification OpenAPI complète plutôt qu’à des fichiers .bru séparés. Pour le contexte, consultez Qu’est-ce que le développement API spec-first ?.

Les tests, mocks et docs dérivent de la même définition

Avec une approche spec-as-code, la spécification OpenAPI sert de base pour :

les endpoints ;
les exemples de réponses ;
les cas de test ;
la documentation ;
le mock server.

Quand la spec change, les éléments liés changent avec elle. Cela réduit les écarts entre contrat, tests et documentation.

Git reste le système d’enregistrement

Le dépôt continue de porter l’historique et les revues. La différence est que l’espace Apidog ajoute une collaboration en direct.

Vous conservez donc :

les branches ;
les pull requests ;
les diffs ;
l’historique Git ;
les validations CI.

Et vous ajoutez :

édition multi-utilisateur ;
synchronisation en temps réel ;
rôles d’accès ;
environnements partagés ;
mock server intégré.

Les rôles sont gérés dans l’espace API

Apidog permet d’appliquer des rôles comme visualiseur, éditeur ou administrateur. C’est plus précis qu’un accès Git global au dépôt.

Les identifiants peuvent être centralisés

Les variables d’environnement partagées permettent de gérer les rotations de tokens au même endroit, au lieu de demander à chaque développeur de modifier un fichier local.

Le mock server est inclus

Bruno ne fournit pas de mock server intégré, ce qui pousse souvent les équipes à chercher une alternative de serveur de maquettes Bruno. Dans Apidog, le mock est généré depuis la spécification.

L’exécution en CI reste possible

Apidog propose un exécuteur CLI. Les tests liés à votre spécification synchronisée peuvent donc s’exécuter dans un pipeline CI/CD, comme vous le feriez avec bru run.

Comparaison rapide

Capacité	Bruno + Git	Mode Git Spec-First d'Apidog
Fichiers dans votre propre dépôt	Oui (`.bru`)	Oui (spécification OpenAPI)
Branche + revue de pull request	Oui	Oui
Exécuteur CI	Oui (`bru run`)	Oui (CLI Apidog)
Support auto-hébergé / GitLab	Oui	Oui
Édition multi-utilisateur en direct	Non	Oui
Contrôle d'accès basé sur les rôles	Non	Oui
Identifiants partagés centralisés	Non	Oui
Serveur de maquettes depuis la spécification	Non	Oui
Documentation + tests dérivés d'un seul fichier	Non	Oui

Le mode Git Spec-First est en bêta. Avant une migration complète, testez-le avec votre propre configuration GitHub, GitLab ou auto-hébergée. Pour aller plus loin, consultez l’intégration et la synchronisation Git d’Apidog, le guide du mode Spec-First, ou cette comparaison Stoplight + Postman vs Apidog.

Quand rester avec Bruno

Bruno + Git reste pertinent si :

toute l’équipe est composée de développeurs ;
tout le monde maîtrise Git ;
les changements en temps réel ne sont pas nécessaires ;
les permissions au niveau dépôt suffisent ;
les secrets peuvent être gérés via un coffre externe ;
les mocks et la documentation sont traités ailleurs.

Dans ce cas, Bruno garde un avantage simple : tout reste local et versionné.

Quand passer à Apidog

Le mode Git Spec-First d’Apidog devient plus adapté si :

vous avez des QA, PM ou stakeholders qui doivent accéder aux API sans utiliser Git ;
l’équipe compte 5 personnes ou plus ;
la coordination via push / pull devient une friction quotidienne ;
vous avez besoin d’une synchronisation en temps réel ;
vous devez appliquer des rôles d’accès plus fins ;
vous voulez centraliser les identifiants ;
vous avez besoin d’un mock server ;
vous voulez générer documentation, tests et mocks depuis la même spec.

L’intérêt principal est que la spécification reste dans votre dépôt. Vous ne quittez pas Git : vous ajoutez une couche d’équipe autour.

Mettre en place un workflow Bruno + Git propre

Si vous restez avec Bruno, utilisez une structure explicite et documentée.

Structure recommandée

api-collections/
  .gitignore
  README.md
  bruno.json
  environments/
    local.json
    staging.json
    production.json
  users-api/
    get-user.bru
    create-user.bru
  orders-api/
    create-order.bru
    list-orders.bru

`.gitignore`

*.secret.json
.env
.env.*

Gestion des environnements

Gardez les fichiers d’environnement sans secrets dans Git :

{
  "baseUrl": "https://api.example.com",
  "token": ""
}

Puis demandez à chaque développeur de créer un fichier local ignoré :

environments/production.secret.json

Les vraies valeurs doivent rester dans le gestionnaire de mots de passe ou le coffre de secrets de l’équipe.

README d’onboarding

Ajoutez un README avec les étapes exactes :

# Collections API

## Installation

1. Cloner le dépôt.
2. Ouvrir `api-collections/` dans Bruno.
3. Copier `environments/production.json` vers `environments/production.secret.json`.
4. Récupérer les secrets dans le coffre d’équipe.
5. Lancer les requêtes ou les tests.

## CI

Les secrets sont injectés via les variables d’environnement du pipeline.

CI/CD

Injectez les variables au moment de l’exécution. Ne commitez jamais les secrets.

Exemple conceptuel :

export API_TOKEN="$API_TOKEN_FROM_CI"
bru run api-collections/

Conclusion

Bruno est solide pour une équipe de développeurs qui accepte un workflow Git strict. Mais ses contournements montrent vite leurs limites dès que l’équipe a besoin de collaboration temps réel, de rôles, de secrets centralisés, de mocks ou d’accès pour des non-développeurs.

Apidog répond à ce cas sans supprimer Git du workflow : la spécification OpenAPI reste dans votre dépôt, tandis que l’espace de travail ajoute la collaboration d’équipe. Pour tester ce modèle sur votre propre API, téléchargez Apidog et connectez-le à votre dépôt existant.