GitHub Actions 시각화 도구 이미지

YAML의 숲에 오신 것을 환영합니다

현재 여러분 팀의 workflow.yml 파일은 몇 줄인가요?

보통 CI/CD는 매우 순수하게 시작됩니다. “그냥 린트, 테스트, 빌드만 하면 돼!” 하지만 प्रोडक्ट이 커지기 시작하죠. 누군가는 E2E 테스트가 실패하면 슬랙에 알람을 보내는 규칙을 추가합니다. 또 누군가는 특정한 브랜치만 배포를 건너뛰는 논리를 덧붙입니다. 정신을 차려보면 여러분은 이미 수백 줄에 달하는 괴물 YAML을 만들어낸 것입니다.

  build:
    needs: [test-frontend, test-backend, check-format]
  deploy:
    needs: [build, security-scan]

저는 다크 모드의 GitHub 화면을 멍하니 바라보며 “잠깐… 프론트엔드 빌드 작업이 정말로 백엔드 테스트가 끝날 때까지 기다려야 하는 건가?”라고 고민하던 때를 기억합니다. 제가 직접 쓴 코드 안에서 길을 잃어가고 있었죠. 인간의 뇌는 평문 텍스트에서 이렇게 깊게 중첩되고 서로 연결된 의존성 그래프를 읽어내도록 설계되지 않았습니다.

보이지 않는 실선 그리기

“이 추상적인 트리를 더 이상 머릿속에 담아둘 수가 없어. 물리적으로 봐야겠어.”

그 좌절감이야말로 이 시각화 도구의 불씨가 되었습니다. 개념은 단순했습니다. 그 거대한 YAML 파일을 붙여넣으면, 똑똑한 자바스크립트가 몰래 침투해 모든 needs: 매개변수를 구문 분석하고, 부모-자식 관계를 잡은 다음, Mermaid.js를 사용하여 화려하게 정리된 순서도를 뱉어내는 것입니다.

개발하면서 예상외로 가장 재미있었던 부분은 오류 처리였습니다. YAML은 악명 높게 잔인한 언어입니다. 들여쓰기 공백 하나만 놓쳐도 전체가 터져버리죠. 그냥 일반적인 “구문 분석 오류”를 던져버리는 대신, 도구가 정확한 줄 번호로 당신에게 화를 내어 진짜로 오타를 찾을 수 있게 도구에 시간을 좀 더 투자했습니다.

요즘 저희 팀은 이 시각화 도구를 새로운 개발자를 온보딩하고 CI 흐름을 설명하기 위한 문서화 도구로 사용하고 있습니다. YAML을 보며 멘탈이 나갈 것 같은 기분이 든다면, 이 곳에 복사해서 붙여넣어 보세요. 당신이 짠 논리가 사실은 아주 아름다운 형태를 띄고 있다는 것을 보고 안도할지도 모릅니다.

그림으로 보면 리뷰의 대화가 달라진다

YAML을 텍스트로 리뷰하면 코멘트는 어쩔 수 없이 사소한 구문 이야기로 흘러갑니다. “여기 들여쓰기가”, “이 needs 배열이” 하는 식으로요. 하지만 그림으로 보여주면 대화의 차원이 한 단계 올라갑니다. “잠깐, 이 보안 스캔이 배포 전제조건에 빠져 있지 않나요?” 같은, 설계 자체에 대한 지적이 자연스럽게 나옵니다.

새로 합류한 동료가 “우리 CI 어떻게 돌아가요?”라고 물을 때도 마찬가지입니다. 수백 줄의 YAML을 함께 스크롤하는 것보다 순서도 한 장을 보여주는 편이 훨씬 빠릅니다. 그림은 코드를 짜는 도구인 동시에, 사람에게 설명하기 위한 공통 언어이기도 합니다. CI가 복잡해지기 시작했다면, 먼저 전체를 그림으로 그려 보는 것이 가장 빠른 길입니다.

자주 묻는 질문

붙여넣은 워크플로 YAML은 외부로 전송되나요?

아니요. YAML 구문 분석과 다이어그램 생성은 전부 브라우저 안에서 완결됩니다. 사내 CI/CD 정의나 작업 이름, 배포 대상이 포함되어 있어도 외부 서버로 전송되지 않습니다.

needs는 어떤 다이어그램으로 그려지나요?

needs:를 읽어 작업 간 부모-자식 관계를 화살표 그래프로 그립니다. 어디가 직렬이고 어디가 병렬인지, 의존성 지정 누락이 없는지를 한눈에 볼 수 있어 YAML을 위에서 아래로 읽는 것보다 실수가 줄어듭니다.

생성한 다이어그램을 GitHub에 붙일 수 있나요?

네. 생성된 Mermaid 코드를 복사해 README나 문서에 그대로 붙일 수 있습니다. 새 팀원에게 CI 구조를 설명하는 자료로도 좋습니다.

YAML 오류로 다이어그램이 표시되지 않을 때는요?

대부분 들여쓰기 어긋남이 원인입니다. YAML은 공백 하나로 구조가 바뀌므로, 작업의 중첩이 맞는지, 탭이 아닌 공백으로 들여썼는지 확인하세요. 오류가 가리키는 줄 주변부터 살펴보면 빠릅니다.