Airflow Breeze Manager(ABM)는 10월 31일 22시에 공개된 따끈따끈한 오픈소스 프로젝트입니다.
이것이 만들어진 배경에는 Airflow 프로젝트에서 여러 기능 브랜치를 동시에 개발해야 하는 상황에서
기존의 Breeze 환경에서는 이런 문제가 있었습니다:
- 여러 Breeze 인스턴스를 띄우면 포트 충돌 발생
- 모든 컨테이너가 동일한 Docker Compose 프로젝트 이름을 사용해 컨테이너 이름 충돌
- 브랜치 전환 시마다 컨텍스트 손실, 이전 환경을 다시 세팅해야 함
- 컨테이너가 다시 시작될 때까지 기다려야 하는 비효율
이런 불편함을 해결하기 위해 ABM은 브랜치마다 완전히 독립된 Breeze 환경을 자동으로 구성합니다.
덕분에 여러 PR을 동시에 작업하더라도 충돌과 rebuild 없이 빠르게 전환할 수 있습니다.
주요 특징
ABM은 각 지점별로 완전히 격리된 환경을 만듭니다.
- Git 작업 트리 격리 — 여러 브랜치를 동시에 체크아웃 가능
- 서비스 포트 자동 할당 — Webserver, Flower, PostgreSQL, MySQL, Redis, SSH 모두 충돌 없이 작동
- Docker Compose 프로젝트 이름 분리 —
COMPOSE_PROJECT_NAME을 활용해 컨테이너 간 충돌 방지 - 브랜치별 문서 관리 — 각 프로젝트별로
PROJECT.md,CLAUDE.md등 별도 유지 - GitHub PR 연동 — 각 브랜치에 연결된 PR 자동 추적
- 디스크 공간 관리 — 오래된 노드 모듈 자동 동결/해제
설치 방법
uv tool install airflow-breeze-manager
초기 설정
airflow 레포지토리 디렉토리에서 아래의 명령어를 실행합니다.
abm init
Use this as the Airflow repository? [Y/n]: 라는 질문이 나오면 Y를 입력합니다.
이후 작업 트리 경로를 묻는 Worktrees will be created in: <경로>메시지가 나오면 경로를 확인 후 Y로 진행하면 됩니다.
정상적으로 완료되면 아래처럼 안내문이 표시됩니다:
abm setup-autocomplete
사용 방법
새 프로젝트 만들기
새로운 브랜치를 만들어서 Breeze 환경을 바로 띄우고 싶다면 아래처럼 입력합니다:
abm add abm-test1 --create-branch
이 명령으로 ABM은 새로운 Git worktree를 만들고 Breeze가 사용할 포트를 자동으로 배정하고 Docker Compose 프로젝트 이름까지 분리하여 완젼히 독립된 개발환경을 세팅합니다.
덕분에 다른 브랜치의 웹서버나 Flower를 미리 띄워놨더라도 포트 충돌 없이 바로 실행됩니다.
기존 브랜치를 ABM 프로젝트로 등록하기
이미 브랜치가 있고 그걸 ABM에서 관리하고 싶다면 이렇게 하면 됩니다:
abm add my-project --branch existing-branch-name
이러면 새로 브랜치를 만들지 않고, 기존 브랜치를 기반으로 ABM 프로젝트를 생성합니다.
이후부터는 이 브랜치도 다른 ABM 프로젝트와 동일하게 Breeze 환경에서 작동합니다.
프로젝트 이름에
/슬래시가 들어가면 현재는 제대로 인식되지 않습니다.
예를 들어feature/version-indicator대신feature-version-indicator처럼 입력해야 합니다.
→ 현재 이 문제는 보고되었으며, Release 0.2.0 · kaxil/abm · GitHub 에서 해결되었습니다.
ABM으로 관리되고 있는 프로젝트 목록 확인하기
현재 어떤 브랜치들이 ABM으로 관리되고 있는지 보려면:
abm list
아래처럼 깔끔한 표가 뜹니다!
각 프로젝트의 상태, 연결된 PR, Breeze 포트 등이 한눈에 볼 수 있습니다.
Breeze Shell 들어가기
특정 브랜치의 Breeze 환경에 바로 들어가고 싶다면:
abm shell my-project
이 명령을 실행하면 자동으로 해당 브랜치의 작업 디렉터리로 이동하고,
적절한 환경변수(COMPOSE_PROJECT_NAME, WEB_PORT, 등)를 세팅한 뒤 Breeze shell을 띄워줍니다.
Breeze start airflow 하기
abm start-airflow my-project
위처럼 Still waiting … 이라는 로그가 나올텐데 조금 인내심을 갖고 기다려주면 아래와 같이 잘 실행됩니다.
그러면 abm list이나 abm status my-project에서 봤던 포트로 접속해줍니다.
정리
Airflow Breeze Manager는 여러 브랜치를 병렬로 개발할 때의 번거로움을 줄여주는 도구입니다.
이제 복잡한 환경 설정이나 컨테이너 충돌에 신경 쓸 필요 없이, 각 브랜치마다 독립된 Breeze 환경에서 빠르게 작업할 수 있게 되었습니다.
저는 아직 여러 기능을 동시에 개발할 일이 없는데, 그래도 브랜치를 옮길 때마다 Breeze 환경을 다시 빌드해야 하는 순간엔 꽤 귀찮게 느껴졌습니다.
그런데 메인테이너 분들처럼 여러 PR을 동시에 관리하는 분들에게는 이 과정이 훨씬 더 큰 귀찮음이었을 것 같습니다.
그런 의미에서 ABM은 정말 ‘필요했던’ 도구라고 생각합니다.
Airflow 프로젝트는 보면 볼 수록 단순히 워크플로우 도구를 만드는 데 그치지 않고, 개발자 경험 자체를 개선하는 도구까지 함께 발전시키고 있는게 Airflow를 더 매력적인 프로젝트로 느끼게 만드는 것 같습니다.
