n8n 워크플로우를 API로 코드처럼 관리하는 방법

워크플로우 JSON을 소스 코드로 취급하기

n8n 편집기에서 만든 워크플로우는 노드, 연결, 설정을 포함한 JSON으로 표현된다. 이 JSON을 API로 수집해 Git에 저장하면 변경 이력, 코드 리뷰, 환경별 배포 절차를 적용할 수 있다. 다만 데이터베이스 전체를 백업하는 방식과 워크플로우 정의를 형상 관리하는 방식은 목적이 다르므로 분리해야 한다.

기본 흐름은 n8n API에서 정의를 가져오고, 실행 환경에 종속된 필드를 제거한 뒤 저장소에 커밋하는 것이다. 배포할 때는 저장된 정의를 대상 인스턴스의 API로 생성하거나 갱신한다. 활성화 여부와 자격 증명은 워크플로우 본문과 별도로 다루는 편이 안전하다.

저장소 구조와 식별 기준 정하기

개발과 운영 인스턴스에서 같은 워크플로우라도 내부 ID는 달라질 수 있다. 따라서 파일명이나 별도 매니페스트에 업무용 식별자를 두고, 환경별 n8n ID를 매핑하는 방식이 적합하다. 이름만 식별자로 사용하면 운영 중 이름 변경이나 중복 때문에 배포 대상을 잘못 찾을 수 있다.

automation/
  workflows/
    order-notification.json
    daily-report.json
  environments/
    staging.json
    production.json
  scripts/
    pull-workflows.py
    deploy-workflows.py

API에서 정의 수집하기

n8n의 공개 API는 일반적으로 API 키를 헤더에 전달해 워크플로우를 조회한다. API 경로와 요청·응답 필드는 설치 버전에 따라 달라질 수 있으므로 사용 중인 인스턴스의 API 문서를 기준으로 구현해야 한다. 다음 명령은 목록을 받아 원본 응답을 확인하는 최소 예시다.

curl -sS "$N8N_URL/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -o workflows-response.json

수집 스크립트는 각 워크플로우를 개별 파일로 나누고 JSON 키 순서와 들여쓰기를 고정해야 한다. 생성 시각, 수정 시각, 환경별 ID처럼 실행 결과에 따라 달라지는 필드는 제거하거나 별도 매니페스트로 이동한다. 정규화가 없으면 실제 로직 변경이 없어도 매번 큰 diff가 발생한다.

자격 증명과 비밀값 제외하기

워크플로우 JSON에는 자격 증명 자체가 아니라 참조 정보가 포함될 수 있지만, 이 참조도 환경마다 다를 가능성이 높다. API 키, 웹훅 비밀값, 토큰을 노드 파라미터에 직접 넣어 커밋해서는 안 된다. 대상 환경에서 미리 생성한 자격 증명을 논리적 이름이나 매핑 파일로 연결하고, 실제 비밀값은 비밀 관리 도구나 CI 변수에서 주입한다.

배포를 생성과 갱신으로 나누기

배포 스크립트는 먼저 업무용 식별자로 대상 워크플로우를 조회한다. 대상이 없으면 생성 API를 호출하고, 있으면 해당 ID에 갱신 요청을 보낸다. 요청 본문은 현재 API 스키마에서 허용하는 필드만 선택하는 허용 목록 방식으로 구성하는 것이 좋다.

1. 저장소의 워크플로우 JSON을 스키마에 맞게 검증한다.
2. 환경별 자격 증명과 변수 매핑을 적용한다.
3. 대상 워크플로우를 조회해 생성 또는 갱신한다.
4. 조회 API로 다시 받아 배포 결과를 비교한다.
5. 검증이 끝난 뒤 필요한 워크플로우만 활성화한다.

활성화와 롤백은 별도 단계로 두기

정의 갱신과 활성화를 한 번에 처리하면 잘못된 설정이 즉시 실행될 수 있다. 먼저 비활성 상태로 배포하고 테스트 실행이나 필수 필드 검사를 통과한 뒤 활성화하는 편이 안전하다. 롤백은 이전 Git 커밋의 JSON을 같은 배포 절차로 다시 적용하되, 실행 중이던 작업과 외부 시스템의 중복 처리 가능성도 함께 확인해야 한다.

CI에서 확인할 항목

• JSON 구문과 필수 노드·연결 구조 검증
• 금지된 평문 토큰과 비밀값 패턴 검사
• 존재하지 않는 자격 증명 참조 검사
• 운영 배포 전 변경 diff와 승인 기록 확인
• 배포 후 API 응답과 저장소 정의 비교

n8n 편집기에서 운영 인스턴스를 직접 수정하면 저장소와 실제 상태가 달라지는 드리프트가 생긴다. 이를 막으려면 운영 편집 권한을 제한하거나 정기적으로 API 결과와 Git 정의를 비교해야 한다. 긴급 수정이 필요했다면 수정 내용을 다시 가져와 리뷰한 뒤 저장소를 기준 상태로 복구한다.

API 자동화의 범위를 명확히 하기

워크플로우 API 관리는 변경 통제와 반복 배포에는 유용하지만 n8n 전체 복구 수단은 아니다. 자격 증명, 사용자 권한, 실행 이력, 인스턴스 설정은 별도 백업과 운영 정책이 필요하다. 워크플로우 정의는 Git, 비밀값은 비밀 관리 시스템, 플랫폼 데이터는 백업 체계로 나누면 책임 범위가 명확해진다.