[Bruno] API 컬렉션을 Git으로 관리하는 법

개발자 도구 · API & DB

[Bruno] API 컬렉션을 Git으로 관리하는 법

Bruno는 API 요청 모음을 클라우드가 아니라 프로젝트 안의 평문 파일로 저장하는 오픈소스 API 클라이언트입니다. Postman을 쓰다가 클라우드 동기화나 로그인이 부담스러웠던 경우를 겨냥합니다. 이 글에서는 Bruno가 정확히 무엇을 대체하는지, 컬렉션이 파일로 저장된다는 게 실제로 어떤 차이를 만드는지, 그리고 처음 설치해 첫 요청을 보내고 환경 변수와 테스트, CLI까지 쓰는 순서를 정리합니다.

Bruno는 Postman의 클라우드 의존을 걷어냅니다

API 클라이언트는 HTTP 요청을 만들어 보내고 그 요청들을 컬렉션으로 묶어 관리하는 도구입니다. Postman이 이 영역의 사실상 표준이지만, 시간이 지나면서 워크스페이스 동기화·계정 로그인·팀 좌석 과금처럼 클라우드를 전제로 한 기능이 늘었습니다. 로그인 없이 빠르게 요청만 던지던 스크래치패드 방식이 사라진 점도 개발자들이 대안을 찾게 된 계기 중 하나로 꼽힙니다.

Bruno는 그 반대 방향을 택한 도구입니다. 요청 컬렉션을 클라우드에 동기화하지 않고, 작업 중인 저장소 안의 폴더와 텍스트 파일로 저장합니다. 계정을 만들 필요도 없고, 데이터는 의도적으로 Git이나 파일 공유로 넘기기 전까지 로컬 머신에 머뭅니다. 핵심 기능은 오픈소스로 공개돼 있고, 일부 부가 기능은 유료 골든 에디션(Golden Edition)으로 제공됩니다.

항목	클라우드 중심 클라이언트	Bruno
컬렉션 저장 위치	주로 서비스 클라우드	로컬 파일(.bru), 프로젝트 폴더 안
계정/로그인	대체로 필요	필요 없음
버전 관리	서비스 내 히스토리	Git 그대로(diff·PR 리뷰)
협업	워크스페이스 초대·좌석	저장소 push/pull로 공유
라이선스	제품마다 상이	오픈소스 + 유료 골든 에디션

컬렉션이 파일이라는 건, 코드처럼 다룬다는 뜻입니다

Bruno의 가장 큰 차이는 컬렉션을 화면 안에만 존재하는 데이터가 아니라 디스크 위의 파일로 둔다는 점입니다. 요청 하나가 .bru 파일 하나로 떨어지고 폴더 구조가 그대로 컬렉션 구조가 됩니다. 그래서 다음이 가능합니다.

• API 컬렉션을 코드와 같은 저장소에 두고 함께 커밋합니다. 엔드포인트가 바뀌면 코드 변경과 같은 PR에 요청 변경도 올라갑니다.
• 요청이 어떻게 바뀌었는지 git diff로 한 줄 단위까지 확인하고, 동료가 리뷰합니다.
• 팀 공유는 별도 초대 절차 없이 저장소를 받아오는 것으로 끝납니다. 접근 권한도 이미 쓰는 Git 권한 체계를 그대로 따릅니다.

여기서 쓰이는 .bru는 JSON이나 YAML이 아니라 Bru라는 별도 마크업 형식입니다. 요청·헤더·본문·검증을 사람이 읽기 쉬운 블록으로 적도록 설계됐습니다. 참고로 Bruno는 새 컬렉션에는 OpenCollection YAML 형식을 권장하는 방향으로 옮겨가고 있지만 기존 .bru 파일도 계속 지원한다고 공식 문서에 명시돼 있습니다.

설치하고 첫 요청을 보내는 순서

시작 절차는 단순합니다.

• 공식 사이트(usebruno.com)에서 데스크톱 앱을 받습니다. macOS는 Homebrew(brew install bruno), Windows는 winget 등 패키지 매니저로도 설치합니다.
• 앱을 열고 Create Collection으로 새 컬렉션을 만들면, 디스크에서 저장할 폴더 위치를 직접 지정합니다. 이 폴더가 곧 Git으로 관리할 대상입니다.
• 컬렉션 안에서 New Request로 요청을 추가하고 메서드와 URL을 입력한 뒤 보냅니다. 이때 폴더에는 요청별 .bru 파일이 생성됩니다.
• 이미 Postman을 쓰고 있다면, Postman 컬렉션과 환경을 Bruno로 가져오는 임포트 기능으로 옮깁니다.

요청을 만들면 디스크에 떨어지는 파일은 대략 이런 모양입니다. 화면에서 채운 값이 그대로 평문으로 보입니다.

meta {
  name: 사용자 목록 조회
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users
  body: none
  auth: none
}

headers {
  Accept: application/json
}

assert {
  res.status: eq 200
}

환경·변수·스크립트·테스트는 이렇게 나뉩니다

환경과 변수

개발·스테이징·운영처럼 호출 대상이 달라질 때를 위해 환경(Environment)을 나눠 둘 수 있습니다. 위 예시의 {{baseUrl}}처럼 변수를 끼워 두면, 같은 요청을 환경만 바꿔 재사용합니다. 변수는 요청·환경·컬렉션 범위로 정의합니다.

사전·사후 스크립트

요청을 보내기 전(pre-request)과 응답을 받은 뒤(post-response)에 실행되는 스크립트를 붙입니다. 보내기 전에 토큰을 만들어 헤더에 넣거나, 응답에서 값을 꺼내 다음 요청에 쓸 변수로 저장하는 식의 흐름을 자동화하는 데 씁니다.

검증(assertion)과 테스트

응답의 상태 코드나 본문 값이 기대와 맞는지 검증을 걸 수 있습니다. 위 예시의 assert 블록이 그 예로, 응답 상태가 200인지 확인합니다. 단발 요청 확인을 넘어 회귀 검증용으로 모아두기 좋습니다.

CLI로 CI 파이프라인에 넣습니다

Bruno에는 bru run 명령을 제공하는 CLI가 있습니다. 데스크톱 앱을 열지 않고도 컬렉션을 명령줄에서 실행하므로, 작성해 둔 요청과 검증을 그대로 CI/CD 파이프라인에 넣어 자동 실행할 수 있습니다. 컬렉션이 저장소 안 파일로 있기 때문에, 코드를 체크아웃한 러너가 별도 동기화 없이 같은 요청 묶음을 그대로 돌릴 수 있다는 점이 자연스럽게 맞물립니다.

# 컬렉션 폴더에서 특정 환경으로 전체 실행
bru run --env staging

미리 알아두면 좋은 점

• 형식 전환기입니다. 새 컬렉션은 OpenCollection YAML 권장으로 옮겨가는 중이고 .bru는 계속 지원됩니다. 새로 시작한다면 어떤 형식으로 만들지 한 번 확인하는 편이 좋습니다.
• 팀 공유 모델이 다릅니다. 워크스페이스 초대 대신 Git 저장소 접근을 전제로 합니다. Git을 쓰지 않는 팀이라면 협업 이점이 약해집니다.
• 비밀값 관리에 주의해야 합니다. 컬렉션이 평문 파일이라, API 키 같은 비밀값을 그대로 적어 커밋하면 저장소에 노출됩니다. 비밀값은 변수와 환경으로 분리하고 커밋 대상에서 빼야 합니다.
• 유료 경계를 확인하세요. 핵심 기능은 무료지만 일부 기능은 골든 에디션으로 제공됩니다. 필요한 기능이 어느 쪽인지 미리 보는 게 좋습니다.

이런 경우에 잘 맞습니다

코드와 API 요청을 같은 저장소에서 함께 버전 관리하고 싶은 경우, 클라우드 동기화나 계정 로그인을 피하고 로컬에서 빠르게 쓰고 싶은 경우, 요청 변경을 PR로 리뷰하는 흐름을 만들고 싶은 경우에 적합합니다. 반대로 GUI 워크스페이스 기반 공유에 이미 익숙하거나 Git을 쓰지 않는 팀이라면 이점이 줄어듭니다. 지금 Postman을 쓰고 있다면 컬렉션 임포트로 한 디렉터리만 옮겨 시험 삼아 써본 뒤 판단하는 방법이 부담이 적습니다.

설치·설정 참고 데스크톱 앱은 usebruno.com에서 받거나 Homebrew·winget으로 설치합니다. 컬렉션을 만들 때 저장 폴더를 직접 지정하고 그 폴더를 Git으로 관리합니다. 비밀값은 변수·환경으로 분리해 커밋 대상에서 제외하세요. CLI는 bru run으로 컬렉션을 명령줄에서 실행합니다.

출처

Bruno 공식 사이트 — usebruno.com Bruno Docs — What is Bruno Bruno Docs — Bru Markup Language Overview Bruno Docs — Bruno CLI (bru run)

직접 사용기가 아니라 공식 문서·사이트를 근거로 정리한 객관 소개입니다. 기능·라이선스 범위는 버전에 따라 달라질 수 있으니 도입 전 공식 문서에서 최신 내용을 확인하시기 바랍니다.