n8n UI를 열지 않고도 퍼블릭 API를 사용해 스크립트와 파이프라인에서 n8n 환경을 관리할 수 있습니다. 이를 통해 인스턴스 간 승격을 자동화할 수 있습니다. 예를 들어 개발 인스턴스의 작업을 일정에 따라, 또는 CI/CD 파이프라인의 일부로 프로덕션에 반영할 수 있습니다.

이 페이지에서는 소스 컨트롤 API 엔드포인트가 함께 동작하는 방식을 설명합니다. 인스턴스를 이미 Git에 연결했고 UI에서 푸시와 풀이 어떻게 동작하는지 이해하고 있다고 가정합니다. 관련 배경은 푸시 및 풀과 환경 간 작업 복사를 참고하세요.

엔드포인트#

퍼블릭 API는 세 가지 소스 컨트롤 작업을 제공합니다.

push와 pull은 소스 컨트롤 메뉴의 Push 및 Pull 버튼과 같은 동작입니다. status는 확인 전에 푸시 및 풀 모달에 UI가 보여주는 파일 목록에 해당합니다. API는 이를 별도의 엔드포인트로 제공하므로, 스크립트가 UI가 인라인으로 수행하는 것과 같은 검토를 할 수 있습니다.

전체 요청 및 응답 스키마는 엔드포인트 레퍼런스를 참고하세요.

인증 및 스코프#

모든 요청에는 X-N8N-API-KEY 헤더로 보내는 API 키가 필요합니다. 엔터프라이즈 플랜에서는 각 키를 필요한 최소 권한으로 스코프를 지정할 수 있습니다.

이처럼 키에 스코프를 지정하면 방향을 강제할 수 있습니다. 변경 사항을 받기만 해야 하는 프로덕션 인스턴스에는 sourceControl:pull 키를 부여하여 푸시할 수 없게 합니다. 풀하기 전에 status로 들어오는 변경 사항을 미리 보려면 해당 키에 sourceControl:read도 추가하세요.

상태를 확인한 다음 실행#

무작정 푸시하지 마세요. push는 fileNames 배열이 필요하며 거기에 나열한 파일만 커밋하므로, 먼저 status를 호출해 대상이 되는 파일을 확인하세요.

절차는 다음과 같습니다.

1. status를 호출해 대상이 되는 파일을 확인합니다.
2. 포함할 항목을 결정합니다. 모든 파일을 선택하면 전체를 푸시하고, 일부만 선택하면 그 일부만 푸시합니다.
3. 선택한 파일에서 각 파일의 id와 type만 남겨 fileNames를 만듭니다.
4. 그 배열로 push를 호출합니다.

status를 호출할 때 direction 쿼리 매개변수로 어느 쪽을 미리 볼지 선택합니다.

curl --request GET \
	--location '/api/v1/source-control/status?direction=push' \
	--header 'X-N8N-API-KEY: '

응답의 각 파일에는 id, name, type(workflow 또는 credential 등), status(modified 또는 new 등)가 포함됩니다.

{
	"data": [
		{
			"id": "1a2b3c",
			"name": "Daily sales report",
			"type": "workflow",
			"status": "modified",
			"file": "workflows/1a2b3c.json"
		}
	]
}

개발에서 읽기 전용 프로덕션으로의 승격 흐름#

일반적인 구성입니다. 개발 인스턴스에서 변경한 뒤, 업데이트를 받기만 하는 프로덕션 인스턴스로 승격합니다. 이 예시는 두 인스턴스가 하나의 Git 브랜치를 공유합니다.

각 인스턴스에 스코프가 지정된 API 키를 부여합니다.

• 개발 인스턴스 API 키에는 sourceControl:read와 sourceControl:push를 부여합니다.
• 프로덕션 인스턴스 API 키에는 sourceControl:read와 sourceControl:pull을 부여합니다.

1. 개발에서 변경 사항을 미리 봅니다. direction=push로 status를 호출해 n8n이 무엇을 커밋할지 확인합니다.

curl --request GET \
	--location '/api/v1/source-control/status?direction=push' \
	--header 'X-N8N-API-KEY: '

2. 개발에서 Git으로 푸시합니다. 커밋 메시지와 승격할 파일을 id/type 쌍으로 fileNames에 나열해 보냅니다. 1단계 status 응답의 모든 파일을 포함하면 전체를 승격하고, 일부만 포함하면 그 일부만 승격합니다.

curl --request POST \
	--location '/api/v1/source-control/push' \
	--header 'Content-Type: application/json' \
	--header 'X-N8N-API-KEY: ' \
	--data '{
		"commitMessage": "Promote sales reporting workflows",
		"fileNames": [
			{
				"id": "1a2b3c",
				"type": "workflow"
			}
		]
	}'

3. 프로덕션에서 변경 사항을 미리 봅니다. direction=pull로 status를 호출해 n8n이 무엇을 적용할지 아무것도 건드리기 전에 확인합니다.

curl --request GET \
	--location '/api/v1/source-control/status?direction=pull' \
	--header 'X-N8N-API-KEY: '

4. 프로덕션으로 풀합니다. 프로덕션 인스턴스가 같은 브랜치를 읽어 변경 사항을 적용합니다. force를 사용하면 들어오는 버전을 수락하고, autoPublish를 설정하면 워크플로가 도착하는 대로 게시합니다.

curl --request POST \
	--location '/api/v1/source-control/pull' \
	--header 'Content-Type: application/json' \
	--header 'X-N8N-API-KEY: ' \
	--data '{
		"force": true,
		"autoPublish": "published"
	}'

autoPublish 매개변수는 none(기본값), published(프로덕션에서 이미 게시된 워크플로만 다시 게시), all(풀한 모든 워크플로 게시) 중 하나를 받습니다. 각 모드에 대한 자세한 내용은 푸시 및 풀을 참고하세요.

예약 백업 흐름#

일정에 따라 인스턴스를 Git으로 버전 관리하려면, 대상이 되는 모든 파일을 가져와 타이머에 맞춰 전체를 푸시합니다. cron 작업, CI 파이프라인, 또는 Schedule Trigger를 사용하는 n8n 워크플로에서 실행할 수 있습니다.

1. 대상이 되는 모든 파일을 가져옵니다. direction=push로 status를 호출합니다.

curl --request GET \
	--location '/api/v1/source-control/status?direction=push' \
	--header 'X-N8N-API-KEY: '

2. 전체 목록을 푸시합니다. status 응답이 반환한 모든 파일을 id와 type으로 매핑하고, 이를 fileNames로 전달합니다. 승격 흐름과 달리 이 작업은 사람 없이 실행되며 force를 true로 설정합니다. 이렇게 하면 충돌 검사를 건너뛰고 항상 브랜치를 인스턴스의 현재 상태로 덮어씁니다. 예약된 실행 전마다 인스턴스에 원하는 버전이 있는지 확인하세요. 그렇지 않으면 Git의 더 최근 변경 사항을 덮어쓸 수 있습니다.

curl --request POST \
	--location '/api/v1/source-control/push' \
	--header 'Content-Type: application/json' \
	--header 'X-N8N-API-KEY: ' \
	--data '{
		"commitMessage": "Scheduled backup",
		"force": true,
		"fileNames": [
			{
				"id": "1a2b3c",
				"type": "workflow"
			},
			{
				"id": "4d5e6f",
				"type": "workflow"
			},
			...
		]
	}'

푸시 충돌 처리#

마지막 동기화 이후 인스턴스와 Git 양쪽에서 파일을 변경했다면 해당 파일은 충돌 상태입니다. status는 이러한 파일을 "conflict": true로 표시합니다. force 없이 push를 호출했을 때 선택한 파일 중 하나라도 충돌 상태이면, n8n은 409 응답으로 푸시 전체를 거부합니다.

{
	"message": "Push blocked by conflicting files. Pass `force: true` to push anyway.",
	"conflicts": [
		{
			"id": "1a2b3c",
			"name": "Daily sales report",
			"type": "workflow",
			"status": "modified",
			"file": "workflows/1a2b3c.json",
			"conflict": true
		}
	]
}

그래도 푸시하여 Git의 충돌 파일을 인스턴스 버전으로 덮어쓰려면 force를 true로 설정하세요.

curl --request POST \
	--location '/api/v1/source-control/push' \
	--header 'Content-Type: application/json' \
	--header 'X-N8N-API-KEY: ' \
	--data '{
		"commitMessage": "Push reviewed workflows only",
		"force": true,
		"fileNames": [
			{
				"id": "1a2b3c",
				"type": "workflow"
			}
		]
	}'

푸시 및 풀 대상#

API는 UI와 같은 리소스를 커밋하고 적용합니다. 워크플로, 자격 증명 스텁, 변수 스텁, 데이터 테이블 스키마, 프로젝트, 폴더, 태그입니다. 전체 목록과 리소스 유형별 병합 동작은 푸시 및 풀을 참고하세요.

관련 리소스#

• 소스 컨트롤 및 환경 사용
• 소스 컨트롤 이해
• 환경 작업
• n8n에서 Git 사용
• 브랜치 패턴 선택
• 소스 컨트롤 설정
• 푸시 및 풀 변경 사항
• 버전 비교
• 환경 간 작업 이동
• 튜토리얼: 소스 컨트롤로 환경 만들기
• 소스 컨트롤: 소스 컨트롤 엔드포인트의 요청 및 응답 스키마입니다.
• 엔드포인트 레퍼런스: 전체 퍼블릭 API 스키마입니다.