DEV Community

Cover image for 브루노 팀용: 클라우드 동기화 대안 및 해결책
Rihpig
Rihpig

Posted on • Originally published at apidog.com

브루노 팀용: 클라우드 동기화 대안 및 해결책

결론부터 말하자면

Bruno에는 내장 클라우드 동기화가 없습니다. 팀에서 Bruno 컬렉션을 공유하려면 보통 Git 저장소, 공유 네트워크 드라이브, 개발 컨테이너 중 하나를 사용합니다. 이 방식들은 작동하지만 실시간 협업, 역할 기반 접근 제어, 중앙 집중식 자격 증명 관리, 목 서버 같은 팀 기능에는 한계가 있습니다. Apidog은 Spec-First Git 모드를 통해 OpenAPI 사양을 저장소에 유지하면서도 선택적 클라우드 협업 기능을 제공합니다. 즉, Git 워크플로우와 팀 작업 공간을 동시에 사용할 수 있습니다.

오늘 Apidog을 사용해 보세요

서론

Bruno의 로컬 전용 디자인은 실수가 아니라 의도된 선택입니다. 사용자 데이터는 사용자의 장치에 남고, 계정이나 구독, 벤더 락인 없이 API 컬렉션을 관리할 수 있습니다.

하지만 팀에서 사용하기 시작하면 문제가 생깁니다.

  • 5명의 개발자가 같은 API 컬렉션을 어떻게 공유할 것인가?
  • QA 엔지니어가 최신 요청을 어떻게 받을 것인가?
  • 신입 개발자가 Slack으로 파일을 주고받지 않고 환경을 어떻게 설정할 것인가?
  • 토큰이 갱신될 때 모든 사람의 로컬 환경을 어떻게 업데이트할 것인가?

이 글에서는 Bruno 팀들이 실제로 사용하는 공유 방식과 각 방식의 비용을 정리합니다. 마지막에는 Bruno의 “파일을 저장소에 둔다”는 철학을 유지하면서 실시간 협업 기능을 추가할 수 있는 Apidog의 Spec-First Git 모드도 함께 살펴봅니다. 더 넓은 배경이 필요하다면 Git과 함께 작동하는 API 도구 모음을 참고하세요.

1. Git 접근 방식: Bruno가 의도한 기본 경로

Bruno는 Git을 중심으로 설계되었습니다. 컬렉션은 .bru 파일이고, 환경은 JSON 파일이며, 모든 데이터는 일반 텍스트입니다. 따라서 가장 자연스러운 공유 방식은 Git 저장소입니다.

설정 방법 

mkdir api-collections
cd api-collections
git init
Enter fullscreen mode Exit fullscreen mode

Bruno에서 컬렉션을 만든 뒤 저장소에 커밋합니다.

git add .
git commit -m "Add Bruno API collection"
git remote add origin git@github.com:your-org/api-collections.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

팀원은 저장소를 클론한 뒤 Bruno에서 해당 폴더를 열면 됩니다.

git clone git@github.com:your-org/api-collections.git
Enter fullscreen mode Exit fullscreen mode

운영 방식

  1. API 요청을 수정합니다.
  2. .bru 파일 변경 사항을 확인합니다.
  3. 브랜치를 만들고 커밋합니다.
  4. Pull Request를 엽니다.
  5. 리뷰 후 병합합니다.
  6. 다른 팀원은 git pull로 최신 컬렉션을 가져옵니다.

장점

  • 모든 요청 변경 사항이 Git 기록에 남습니다.
  • API 변경도 코드처럼 리뷰할 수 있습니다.
  • CI/CD에서 bru run을 실행하기 쉽습니다.
  • GitHub, GitLab, Bitbucket 등 기존 Git 호스트를 그대로 사용할 수 있습니다.
  • 개발자 중심 팀에는 익숙한 워크플로우입니다.

단점

  • Git에 익숙하지 않은 QA, PM, 파트너는 사용하기 어렵습니다.
  • 변경 사항이 실시간으로 보이지 않습니다.
  • 토큰, 비밀번호 같은 보안 값은 커밋할 수 없어 별도 관리가 필요합니다.
  • 두 사람이 같은 요청을 수정하면 병합 충돌이 발생할 수 있습니다.
  • “보기만 가능” 같은 API 컬렉션 수준 권한을 표현하기 어렵습니다.

적합한 팀

Git을 일상적으로 사용하는 2~8명 규모의 개발자 팀에 적합합니다. 이 방식은 Git을 사용한 OpenAPI 버전 제어와 같은 접근 방식과 잘 맞습니다.

2. 공유 네트워크 드라이브 접근 방식

일부 팀은 Bruno 컬렉션 폴더를 NAS, 네트워크 파일 서버, Dropbox, Google Drive 같은 공유 폴더에 둡니다.

설정 방법

  1. 공유 드라이브에 폴더를 만듭니다.
  2. Bruno 컬렉션을 해당 폴더에 저장합니다.
  3. 팀원들이 같은 폴더를 Bruno에서 엽니다.

예시:

Shared Drive/
  api-collections/
    users-api/
    orders-api/
    environments/
Enter fullscreen mode Exit fullscreen mode

장점

  • Git이 필요 없습니다.
  • 설정이 간단합니다.
  • 비개발자도 파일 탐색기만 사용할 수 있으면 접근할 수 있습니다.
  • 모든 사람이 같은 폴더를 봅니다.

단점

  • 안정적인 버전 기록이 없습니다.
  • 동시에 편집하면 파일이 덮어쓰이거나 손상될 수 있습니다.
  • 대규모 컬렉션에서는 네트워크 지연이 체감됩니다.
  • 권한 제어가 파일 시스템 수준에 그칩니다.
  • 비밀 값은 여전히 별도로 관리해야 합니다.
  • 오프라인 상태에서는 사용성이 떨어집니다.

적합한 팀

동시 편집이 거의 없는 2~3명 규모의 소규모 팀에만 적합합니다. 장기적인 팀 워크플로우로는 권장하기 어렵습니다.

3. Gitpod / 개발 컨테이너 접근 방식

일부 팀은 Bruno 컬렉션을 Gitpod 작업 공간이나 개발 컨테이너에 포함합니다. 이렇게 하면 모든 개발자가 동일한 API 테스트 환경을 얻을 수 있습니다.

Gitpod / 개발 컨테이너 예시

설정 방식

컬렉션을 저장소에 포함하고, 개발 컨테이너 설정에서 Bruno CLI 또는 관련 도구를 설치합니다.

예시 구조:

repo/
  .devcontainer/
    devcontainer.json
  api-collections/
    bruno.json
    users-api/
    orders-api/
Enter fullscreen mode Exit fullscreen mode

예시 devcontainer.json:

{
  "name": "api-dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "postCreateCommand": "npm install -g @usebruno/cli"
}
Enter fullscreen mode Exit fullscreen mode

CI 또는 컨테이너 내부에서 다음처럼 실행할 수 있습니다.

bru run api-collections
Enter fullscreen mode Exit fullscreen mode

장점

  • 모든 개발자가 동일한 환경을 사용합니다.
  • API 컬렉션이 코드베이스와 같은 버전에 묶입니다.
  • 로컬 설정 부담이 줄어듭니다.
  • CI와 연결하기 쉽습니다.

단점

  • 여전히 Git 기반이므로 비개발자에게는 장벽이 있습니다.
  • 대부분의 컨테이너 환경에서는 Bruno 데스크톱 GUI가 아니라 CLI 중심으로 사용합니다.
  • 실시간 협업은 제공되지 않습니다.
  • 자격 증명 관리는 별도 비밀 관리 체계가 필요합니다.

적합한 팀

이미 Gitpod, Codespaces, Dev Container를 사용하고 있고 API 테스트를 개발 환경에 포함하려는 팀에 적합합니다.

4. 개발자별 복사본 접근 방식

가장 단순하지만 가장 위험한 방식입니다. 각 개발자가 자신의 Bruno 컬렉션을 유지하고, 필요할 때 내보내기 파일이나 문서를 통해 수동으로 동기화합니다.

장점

  • 설정이 거의 필요 없습니다.
  • 개인 개발자는 빠르게 시작할 수 있습니다.
  • 조정 비용이 당장은 낮습니다.

단점

  • 컬렉션이 즉시 분기됩니다.
  • 팀의 단일 진실 원천이 없습니다.
  • 누가 최신 요청을 가지고 있는지 알기 어렵습니다.
  • API 변경이 문서, 테스트, 실제 요청에 다르게 반영될 수 있습니다.
  • 유지 관리 비용이 빠르게 증가합니다.

적합한 팀

개인 개발자에게만 적합합니다. 팀 단위에서는 기술 부채가 되기 쉽습니다.

Bruno 공유 방식들이 공통으로 갖는 한계

Git, 공유 드라이브, 개발 컨테이너 모두 문제를 어느 정도 해결하지만, 다음 한계는 공통적으로 남습니다.

1. 실시간 협업이 없습니다

Git에서는 한 사람이 변경 사항을 커밋하고 푸시해야 다른 사람이 풀해서 볼 수 있습니다.

git pull
Enter fullscreen mode Exit fullscreen mode

API 설계 회의나 디버깅 세션처럼 여러 명이 동시에 요청을 수정하는 상황에서는 이 방식이 느립니다.

2. 역할 기반 접근 제어가 어렵습니다

Git 권한은 보통 저장소 단위입니다.

  • 읽기
  • 쓰기
  • 관리자

하지만 API 협업에서는 더 세밀한 권한이 필요할 수 있습니다.

  • 요청은 실행 가능하지만 편집은 불가
  • 특정 프로젝트만 접근 가능
  • 문서는 볼 수 있지만 환경 변수는 볼 수 없음
  • 외부 계약자는 제한된 폴더만 접근 가능

Bruno + Git만으로는 이런 모델을 표현하기 어렵습니다.

3. 공유 자격 증명 관리가 어렵습니다

Bruno의 비밀 변수는 커밋하지 않는 것이 맞습니다. 하지만 그 결과 모든 팀원이 로컬에서 직접 설정해야 합니다.

예시:

environments/
  production.json
  production.secret.json   # gitignore
Enter fullscreen mode Exit fullscreen mode

토큰이 갱신될 때마다 다음 작업이 필요합니다.

  1. 토큰 발급
  2. 비밀번호 관리자 업데이트
  3. 팀에 공지
  4. 각자 로컬 secret 파일 수정
  5. 누락된 사람 디버깅

작은 팀에서는 괜찮지만, 인원이 늘면 반복적인 운영 비용이 됩니다.

4. 컬렉션 수준 댓글과 협업 맥락이 부족합니다

Git PR 댓글은 diff에는 달 수 있지만, 라이브 컬렉션 안에서 특정 요청에 맥락을 남기는 방식은 아닙니다.

예를 들어 다음과 같은 협업이 어렵습니다.

  • “이 헤더는 다음 릴리스에서 제거 예정”
  • “QA는 staging 환경에서만 이 요청 실행”
  • “이 응답 예시는 모바일 팀과 합의된 계약”

Apidog의 Spec-First Git 모드: Git을 유지하면서 팀 기능 추가하기

일반적으로 팀은 “Bruno + Git” 또는 “클라우드 API 도구” 중 하나를 선택해야 한다고 생각합니다. 하지만 Apidog의 Spec-First Git 모드는 이 선택지를 줄입니다.

OpenAPI 사양을 GitHub, GitLab 또는 자체 호스팅 저장소에 두고, 그 위에 협업 기능을 추가하는 방식입니다.

Apidog Spec-First Git 모드

1. OpenAPI 사양을 저장소에 둡니다

Bruno가 .bru 파일을 저장소에 두는 것처럼, Apidog Spec-First Git 모드에서는 OpenAPI 사양이 저장소의 단일 진실 원천이 됩니다.

예시:

api-spec/
  openapi.yaml
Enter fullscreen mode Exit fullscreen mode

일반적인 워크플로우는 다음과 같습니다.

git checkout -b feature/add-user-api
# openapi.yaml 수정
git add openapi.yaml
git commit -m "Add user API contract"
git push origin feature/add-user-api
Enter fullscreen mode Exit fullscreen mode

이후 Pull Request에서 API 계약 변경 사항을 리뷰합니다.

이 접근 방식은 Spec-first API 개발의 원칙과 맞닿아 있습니다.

2. 설계, 테스트, 목, 문서를 하나의 사양에서 파생합니다

OpenAPI 사양이 바뀌면 다음 산출물이 같은 정의를 기준으로 움직입니다.

  • API 설계
  • 요청/응답 예시
  • 테스트 케이스
  • 목 서버
  • 게시된 API 문서

Bruno에서는 요청 파일 중심으로 관리합니다. 반면 Spec-First 방식에서는 하나의 OpenAPI 파일이 여러 도구의 기준점이 됩니다. 이는 코드형 사양 접근 방식의 핵심입니다.

3. Git 기록과 실시간 협업을 함께 사용합니다

Git은 변경 이력과 리뷰를 담당합니다. Apidog 작업 공간은 실시간 협업을 담당합니다.

즉, 다음 두 가지를 동시에 얻을 수 있습니다.

  • Pull Request 기반 검토
  • 팀원이 같은 API를 편집할 때 실시간 반영

Bruno + Git에서는 git pull 전까지 다른 사람의 변경 사항을 볼 수 없습니다. Apidog에서는 저장소는 유지하면서도 앱 안에서는 협업 세션을 사용할 수 있습니다.

4. 역할 기반 접근 제어를 추가합니다

Apidog에서는 저장소 권한만으로 표현하기 어려운 협업 역할을 사용할 수 있습니다.

예시:

  • 뷰어
  • 편집자
  • 관리자

이를 통해 다음과 같은 구성이 가능합니다.

  • 이해관계자는 요청 실행만 가능
  • 계약자는 특정 프로젝트만 접근
  • 관리자만 환경과 설정 수정
  • 외부 팀은 문서 중심으로 접근

5. 자격 증명을 중앙에서 관리합니다

토큰이나 환경 변수는 각 개발자의 로컬 파일에 흩어지기 쉽습니다.

Apidog의 클라우드 환경을 사용하면 공유 변수를 중앙에서 관리할 수 있습니다. 토큰이 갱신될 때 모든 개발자에게 로컬 파일 수정을 요청하는 대신, 한 곳에서 업데이트합니다.

6. 목 서버를 사양에서 생성합니다

Bruno에는 내장 목 서버가 없어 많은 팀이 Bruno 목 서버 대안을 찾습니다.

Apidog에서는 OpenAPI 사양을 기준으로 목 서버를 생성할 수 있습니다. 따라서 백엔드 구현이 끝나기 전에도 프론트엔드 팀이 실제적인 응답 구조를 기준으로 개발을 시작할 수 있습니다.

7. CI에서 실행할 수 있습니다

Bruno에서 bru run을 사용하는 것처럼, Apidog도 CLI 러너를 통해 테스트를 파이프라인에서 실행할 수 있습니다.

예시 흐름:

name: API Tests

on:
  push:
    branches:
      - main

jobs:
  api-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run API tests
        run: |
          # Apidog CLI 실행 단계
          echo "Run API tests with Apidog CLI"
Enter fullscreen mode Exit fullscreen mode

실제 명령은 팀의 Apidog 설정과 CI 환경에 맞게 구성하면 됩니다.

Bruno + Git vs Apidog Spec-First Git 모드

기능 Bruno + Git Apidog Spec-First Git 모드
개인 저장소 내 파일 예 (.bru) 예 (OpenAPI 사양)
브랜치 + Pull Request 검토 예 예
CI 러너 예 (bru run) 예 (Apidog CLI)
자체 호스팅 / GitLab 지원 예 예
실시간 다중 사용자 편집 아니요 예
역할 기반 접근 제어 아니요 예
중앙 집중식 공유 자격 증명 아니요 예
사양 기반 목 서버 아니요 예
하나의 파일에서 파생된 문서 + 테스트 아니요 예

Spec-First Git 모드는 베타 버전이므로, 팀 전체를 옮기기 전에 테스트 저장소에서 GitHub 또는 GitLab 연동을 먼저 검증하는 것이 좋습니다. 설정 세부 사항은 Apidog의 Git 통합 및 동기화와 Spec-First 모드 가이드를 참고하세요. 설계 도구와 테스트 도구를 함께 평가 중이라면 Stoplight + Postman vs Apidog도 비교 기준이 됩니다.

Bruno를 유지할 때

다음 조건에 해당하면 Bruno + Git을 유지해도 충분합니다.

  • 팀원이 모두 개발자입니다.
  • 모두 Git에 익숙합니다.
  • 실시간 동기화가 꼭 필요하지 않습니다.
  • 저장소 단위 권한이면 충분합니다.
  • 비밀 값은 별도 비밀번호 관리자나 시크릿 저장소로 관리할 수 있습니다.
  • API 문서, 목 서버, 테스트를 다른 도구로 관리해도 괜찮습니다.

이 경우 Bruno의 단순함은 장점입니다. 불필요한 클라우드 계층 없이 로컬 파일과 Git만으로 API 요청을 관리할 수 있습니다.

Apidog으로 전환을 고려할 때

다음 상황이라면 Apidog의 Spec-First Git 모드를 검토할 만합니다.

  • Git을 사용하지 않는 QA, PM, 파트너도 API에 접근해야 합니다.
  • 팀원이 5명 이상이고 Git 기반 조정이 자주 병목이 됩니다.
  • API 설계 또는 디버깅 세션에서 실시간 협업이 필요합니다.
  • 저장소 단위보다 세밀한 접근 제어가 필요합니다.
  • 토큰 갱신 때마다 로컬 비밀 파일을 수정시키는 방식이 부담됩니다.
  • API 클라이언트와 함께 목 서버가 필요합니다.
  • OpenAPI 사양을 단일 진실 원천으로 관리하고 싶습니다.

중요한 점은, 이 전환이 Git을 포기한다는 뜻이 아니라는 것입니다. 사양은 여전히 저장소에 있고, Pull Request 기반 리뷰도 유지됩니다. 그 위에 팀 협업 레이어를 추가하는 방식입니다.

실제로 작동하는 Bruno + Git 워크플로우 설정하기

Bruno를 계속 사용한다면 최소한 다음 구조를 권장합니다.

저장소 구조 

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

.gitignore 예시 

*.secret.json
.env
.env.*
.DS_Store
Enter fullscreen mode Exit fullscreen mode

환경 파일 관리

비밀 값은 커밋하지 않습니다.

environments/
  production.json
  production.secret.json
Enter fullscreen mode Exit fullscreen mode

production.json에는 변수 이름만 둡니다.

{
  "baseUrl": "https://api.example.com",
  "token": ""
}
Enter fullscreen mode Exit fullscreen mode

production.secret.json은 로컬에서만 관리합니다.

{
  "token": "real-production-token"
}
Enter fullscreen mode Exit fullscreen mode

실제 토큰은 비밀번호 관리자나 사내 시크릿 저장소에 보관하고, README.md에 위치만 안내합니다.

신규 개발자 온보딩 절차

README.md에 다음 절차를 명확히 적어두세요.

## Bruno 컬렉션 설정

1. 저장소를 클론합니다.
Enter fullscreen mode Exit fullscreen mode


bash
git clone git@github.com:your-org/api-collections.git


2. Bruno에서 `api-collections` 폴더를 엽니다.

3. 환경 파일을 복사합니다.
Enter fullscreen mode Exit fullscreen mode


bash
cp environments/production.json environments/production.secret.json


4. 비밀번호 관리자에서 토큰을 가져와 `production.secret.json`에 입력합니다.

5. Bruno에서 환경을 선택하고 요청을 실행합니다.
Enter fullscreen mode Exit fullscreen mode

브랜치 전략

API 변경도 코드 변경처럼 다루는 것이 좋습니다.

git checkout -b feature/add-order-endpoint
Enter fullscreen mode Exit fullscreen mode

변경 후:

git add .
git commit -m "Add create order request"
git push origin feature/add-order-endpoint
Enter fullscreen mode Exit fullscreen mode

Pull Request에서는 다음을 확인합니다.

  • 요청 URL이 올바른가?
  • 메서드가 올바른가?
  • 헤더와 인증 방식이 맞는가?
  • 예시 바디에 실제 비밀 값이 없는가?
  • 환경 파일에 비밀 값이 커밋되지 않았는가?

CI/CD에서 실행하기

비밀 파일을 저장소에 넣지 말고, CI 환경 변수로 주입하세요.

예시 GitHub Actions 구조:

name: Bruno API Tests

on:
  push:
    branches:
      - main

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli

      - name: Run Bruno tests
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          bru run api-collections
Enter fullscreen mode Exit fullscreen mode

마무리

Bruno의 로컬 전용 철학은 명확한 장점이 있습니다. 단순하고, 파일 기반이며, Git과 잘 맞습니다. 개발자 중심의 작은 팀이라면 충분히 효과적인 선택입니다.

하지만 팀 규모가 커지고, 비개발자 협업이 필요해지고, 실시간 동기화와 권한 관리, 중앙 집중식 자격 증명, 목 서버가 필요해지면 Git만으로는 부족해집니다.

이때 Apidog의 Spec-First Git 모드는 Git 워크플로우를 버리지 않고 협업 기능을 추가하는 선택지가 될 수 있습니다. OpenAPI 사양은 저장소에 유지하고, 팀은 그 위에서 실시간 협업과 테스트, 문서, 목 서버를 함께 사용할 수 있습니다.

기존 저장소를 연결해 차이를 확인하려면 Apidog을 다운로드해서 직접 테스트해 보세요.

Top comments (0)