커뮤니티 노드 만들기

커뮤니티 노드 만들기 (Building community nodes)

커뮤니티 노드는 npm 레지스트리에 호스팅되는 npm 패키지입니다. 커뮤니티 노드 저장소에 제출할 노드를 만든다면, 아래 자료를 활용해서 노드 구성이 올바른지 확인하는 것이 좋아요.

n8n은 노드를 빌드·테스트할 때 n8n-node CLI 도구를 사용하길 권장합니다. 특히 노드를 검증 제출할 계획이라면 중요해요. 이 도구를 쓰면 노드가 올바른 구조를 갖추고 커뮤니티 노드 요구사항을 따르게 됩니다. 린트와 테스트도 단순해지죠.
n8n 자체 노드들을 보면 노드에 쓸 수 있는 패턴의 예시를 확인할 수 있어요.
나만의 노드 만들기 문서도 참고하세요.
노드가 아래 커뮤니티 노드 표준을 지키는지 확인하세요.

출처: n8n — Building community nodes (공식 문서)

표준 (Standards)

n8n-node 도구로 개발하면 n8n 커뮤니티 노드 저장소에 노드를 등록하는 데 필요한 다음 표준을 자연스럽게 따르게 됩니다:

패키지 이름은 n8n-nodes- 또는 @<scope>/n8n-nodes-로 시작해야 해요. 예: n8n-nodes-weather, @weatherPlugins/n8n-nodes-weather.
패키지 키워드에 n8n-community-node-package를 포함하세요.
노드와 크레덴셜을 package.json 파일의 n8n 속성 안에 추가해야 합니다.
린터(npm run lint)로 노드를 점검하고 로컬에서 테스트(npm run dev)해서 동작을 확인하세요.
패키지를 npm에 배포합니다. n8n Creator Portal을 통해 검증 제출할 계획이라면, 프로비넌스 스테이트먼트가 있는 GitHub Actions 워크플로우로 배포해야 해요. 아래 npm에 배포하기를 참고하세요.

npm에 배포하기 (Publishing to npm)

Creator Portal 검증에 필수

2026년 5월 1일부터 검증 제출되는 노드는 프로비넌스 스테이트먼트가 있는 GitHub Actions로 배포해야 합니다. n8n은 로컬 머신에서 직접 배포한 검증 노드를 받아들이지 않아요.

n8n Creator Portal을 통해 검증 제출하려면, 프로비넌스 스테이트먼트가 있는 GitHub Actions 워크플로우로 배포하세요. 프로비넌스 덕분에 누구나 특정 저장소·커밋의 특정 워크플로우가 그 패키지를 만들었다는 사실을 암호학적으로 검증할 수 있어요. GitHub Actions는 자체 OIDC 인프라로 프로비넌스 스테이트먼트를 서명합니다.

새 노드 (New nodes)

npm create @n8n/node로 노드를 스캐폴드하면 사용 준비가 끝난 publish.yml 워크플로우가 포함됩니다. 로컬에서 npm run release를 실행하면 버전을 올리고, 커밋하고, 태그하고, 푸시해요. 이게 워크플로우를 트리거해서 npm에 배포합니다.

기존 노드 (Existing nodes)

n8n-nodes-starter의 배포 워크플로우를 저장소의 .github/workflows/publish.yml에 추가하세요.

또한 프로젝트에 @n8n/node-cli 버전 0.23.0 이상이 devDependency로 있어야 합니다. 워크플로우가 쓰는 프로비넌스 플래그를 이전 버전이 지원하지 않기 때문이에요:

npm list @n8n/node-cli

일회성 설정 (One-time setup)

npm이 패키지를 대신 배포하도록 저장소의 GitHub Actions 워크플로우를 신뢰하도록 구성하세요. 장기 토큰은 필요 없어요:

npmjs.com에 로그인해 패키지 설정을 엽니다.
Publish access > Trusted Publishers에서 Add a publisher를 클릭해요.
GitHub Actions를 선택하고 다음을 입력합니다:
- Repository owner: 본인의 GitHub 사용자명 또는 조직
- Repository name: 본인의 저장소 이름
- Workflow name: publish.yml (워크플로우의 name: 필드가 아니라 파일명이에요)

토큰을 쓰고 싶다면 npmjs.com에서 Granular Access Token을 만들고 저장소의 Actions secrets에 NPM_TOKEN으로 저장하세요. 자세한 내용은 워크플로우 파일의 주석을 참고하세요.

n8n 검증을 위한 노드 제출하기

n8n은 검증 커뮤니티 노드를 심사해요. 사용자는 n8n의 노드 패널에서 검증 커뮤니티 노드를 발견·설치할 수 있습니다. 이 노드들은 특정 기술·UX 표준과 제약을 지켜야 합니다.

검증에는 GitHub Actions 배포 필요

2026년 5월 1일부터 n8n Creator Portal을 통한 검증 제출은 프로비넌스 스테이트먼트가 있는 GitHub Actions로 배포된 노드여야 합니다. 설정 방법은 npm에 배포하기를 참고하세요.

n8n의 심사를 위해 노드를 제출하기 전에 반드시:

n8n-node 도구가 생성한 스캐폴딩에서 시작하세요. 엄격히 필수는 아니지만, n8n은 검증 제출할 커뮤니티 노드에는 n8n-node CLI 도구를 쓰길 강력히 권장합니다. 이 도구를 쓰면 노드가 기대되는 관례를 따르고 커뮤니티 노드 요구사항을 준수하게 돼요.
노드가 검증 커뮤니티 노드 기술 가이드라인을 따르고 모든 자동 검사를 통과하는지 확인하세요. 특히 검증 커뮤니티 노드는 런타임 의존성을 사용할 수 없습니다.
노드가 UX 가이드라인을 따르는지 확인하세요.
npm 패키지의 README 또는 관련 공개 저장소 형태로 노드에 적절한 문서가 있는지 확인하세요.
npm에 배포하기에서 설명한 대로, 노드를 프로비넌스가 있는 GitHub Actions 워크플로우로 npm에 배포하세요. n8n은 거기서 노드를 가져와 최종 심사를 진행해요.

제출 준비가 되셨나요? (Ready to submit?)

노드가 위 요구사항을 모두 충족하면 n8n Creator Portal에 가입·로그인해 검증을 제출하세요. n8n은 자사의 유료 기능, 특히 엔터프라이즈 기능과 경쟁하는 노드는 거절할 권리를 보유합니다.

커뮤니티 노드 만들기