저장소 변경 사항 검토와 검증을 위한 안정적인 n8n 워크플로 구축

안전한 패턴: 먼저 추출하고, 검사를 마친 뒤에만 실행

저장소 워크플로에서 AI 에이전트에 코드 편집이나 병합 권한을 제한 없이 부여하지 마세요. n8n으로 풀 리퀘스트의 메타데이터와 diff를 가져오고, 모델에 제한된 형식의 요약을 요청한 다음 응답을 검증하고 테스트 상태를 확인하세요. 그 후에야 풀 리퀘스트 병합과 같은 중요한 작업을 사람의 승인 단계로 전달합니다.

이렇게 분리해야 하는 이유는 분명합니다. 그럴듯한 요약이 변경 사항의 정확성을 입증하지는 않으며, 모델이 성공적으로 응답했다고 해서 테스트가 통과한 것도 아닙니다. 정보 추출, 검증, 승인을 각각 별도의 관문으로 다루세요.

아래 설계는 예시일 뿐, 테스트를 거친 n8n 내보내기 파일이 아닙니다. 노드 이름과 사용 가능한 필드는 n8n 버전, 저장소 제공업체, 선택한 모델 API에 따라 달라집니다. 배포하기 전에 관련 노드 문서와 매개변수 지원 여부를 확인하세요.

사전 준비

• 저장소 제공업체와 사용할 모델 엔드포인트에 대한 자격 증명이 설정된 n8n 워크플로
• 풀 리퀘스트 이벤트를 위한 트리거 또는 초기 테스트용 수동 트리거
• 테스트 결과를 보고할 수 있는 저장소 브랜치 보호 또는 CI 프로세스
• 승인 게이트가 있는 도구를 워크플로에서 호출할 경우, 사람의 승인을 받을 검토 채널
• 범위에 포함할 파일, 작업, 저장소를 정한 정책

먼저 읽기 전용 워크플로부터 시작하세요. 추출 단계에 비밀 정보, 환경 파일 전체, 관련 없는 저장소 내용을 전달하지 마세요. diff를 풀 리퀘스트의 변경 파일로 제한하고 최대 페이로드 크기를 설정하세요. 변경 사항이 너무 크면 나누어 처리하거나 수동 검토로 보내세요.

추출 및 검증 경로 만들기

실용적인 처리 순서는 다음과 같습니다.

1. 트리거 및 가져오기: 풀 리퀘스트 식별자를 받은 다음 저장소 제공업체에서 제목, 대상 및 소스 리비전, 변경 파일 목록, diff를 가져옵니다.
2. 필터링: 저장소가 허용 목록에 없거나, diff가 크기 제한을 초과하거나, 민감한 경로가 포함된 경우 처리를 중단하거나 수동 처리로 보냅니다.
3. 추출: 모델에 검토를 돕는 정보만 담은 작은 JSON 객체를 요청합니다. 예를 들어 변경 사항 요약, 영향받는 영역, 명시된 위험, 사람의 주의가 필요한 질문을 포함할 수 있습니다. 테스트 결과를 지어내거나 코드가 안전하다고 주장하지 말라고 지시하세요.
4. 파싱 및 검증: Code 노드나 다른 검증 단계에서 응답을 파싱하고 필수 필드와 형식을 확인합니다. 유효하지 않은 출력은 작업 노드로 넘기지 말고 통제된 오류 분기로 보냅니다.
5. 검증: 저장소 제공업체의 검사 결과나 CI 상태를 정확한 헤드 리비전에 대해 조회합니다. 필수 검사가 완료되고 성공한 경우에만 다음 단계로 진행합니다. 검사가 없거나 대기 중이라면 통과로 간주하지 마세요.
6. 검토: 검증된 요약, PR 링크, 리비전, 검사 결과를 사람에게 보여 줍니다. 병합 등 쓰기 권한이 있는 도구는 승인 뒤에만 실행되도록 합니다.

다음은 추출 결과에 사용할 수 있는 스키마 예시입니다. 이는 워크플로의 계약을 보여 주는 것으로, 모든 모델 엔드포인트가 스키마로 제약된 출력을 기본 지원한다는 뜻은 아닙니다.

{
  "type": "object",
  "required": ["summary", "affected_areas", "risk", "review_questions"],
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "affected_areas": {
      "type": "array",
      "items": { "type": "string" }
    },
    "risk": { "enum": ["low", "medium", "high", "unknown"] },
    "review_questions": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "additionalProperties": false
}

엔드포인트에서 이 스키마를 강제할 수 없다면 응답을 받은 뒤 검증하세요. 예상하지 못한 필드는 거부하고, 문자열과 배열의 길이에 상한을 두며, 파싱이나 검증에 실패하면 워크플로가 안전하게 중단되도록 실질적인 제한도 적용해야 합니다. 누락된 값을 안심을 주는 기본값으로 조용히 대체하지 마세요.

잘못된 데이터가 아니라 일시적 오류만 재시도

시간 초과나 요청 제한처럼 요청이 일시적으로 실패한 경우에는 재시도가 유용합니다. 지연 시간을 포함한 제한적 재시도 정책을 사용하고, 재시도 횟수를 모두 소진하면 풀 리퀘스트 ID와 실패 이유를 기록하는 오류 분기로 보냅니다. 무한 반복은 피하세요.

모든 오류를 자동으로 재시도하지 마세요. JSON 형식 오류, 필수 필드 누락, 지원되지 않는 매개변수, 유효하지 않은 자격 증명은 별도로 처리해야 합니다. 작업을 중지하고 오류를 기록한 뒤 요청을 수정하거나 사람의 확인을 요청하세요. 같은 잘못된 요청을 반복하면 결과는 나아지지 않은 채 시간만 낭비할 수 있습니다.

반복 실행을 위해 워크플로 기록을 저장소, 풀 리퀘스트, 헤드 리비전에 연결하세요. 쓰기 작업 전에 현재 리비전을 다시 가져오고 상태를 확인합니다. 정보 추출이나 테스트 이후 풀 리퀘스트가 변경되었다면 이전 결과를 무효화하고 검사를 다시 실행하세요. 이렇게 하면 한 리비전에 대한 승인이 다른 리비전에 적용되는 일을 막을 수 있습니다.

중요한 도구에 사람의 승인 추가

n8n에서는 AI Agent가 선택한 도구를 실행하기 전에 사람의 승인을 요구할 수 있습니다. 문서에 설명된 흐름에서는 워크플로가 일시 중지되고, 구성된 채널을 통해 승인 요청이 전송됩니다. 검토자가 승인한 경우에만 제안된 입력으로 도구 실행을 계속하며, 거부하면 작업이 취소됩니다. 연결된 모든 도구에 검토를 적용하거나 특정 도구만 선택할 수 있습니다. 자세한 내용은 n8n 휴먼 인 더 루프 문서를 참고하세요.

저장소 워크플로에서는 정보 추출과 상태 확인을 읽기 전용으로 유지하고, 병합 기능이 있는 도구를 검토 뒤에 배치하세요. 검토자에게 PR URL, 정확한 헤드 리비전, 검증된 요약, 테스트 상태, 도구 매개변수를 보여 주세요. n8n 문서에서는 $tool.name과 $tool.parameters를 사용해 승인 메시지를 구성하는 방법을 설명합니다. 해당 매개변수를 읽기 쉬운 요청에 포함하되, 승인 메시지가 리비전과 CI 상태 확인을 대신하게 해서는 안 됩니다.

에이전트 지침에 검토 설정을 명확히 설명하세요. 어떤 도구에 승인이 필요한지, 거부가 무엇을 의미하는지, 그다음 에이전트가 어떻게 해야 하는지를 정합니다. 거부되면 병합 경로를 종료하고 PR은 논의나 수정이 가능하도록 남겨 두어야 합니다. 승인 없이 다른 쓰기 작업을 대안으로 실행해서는 안 됩니다.

문제 해결 및 제한 사항

• 모델이 JSON 앞뒤에 일반 문장을 반환함: 엄격하게 파싱하고 오류 경로로 보냅니다. 엔드포인트가 지원한다면 구조화된 출력을 요청하되, 지원 여부를 확인하고 가정하지 마세요.
• 테스트가 아직 실행 중임: 완료될 때까지 기다리거나 대기 상태로 중단합니다. “아직 실패가 보고되지 않음”을 성공으로 해석하지 마세요.
• 승인 후 새 커밋이 추가됨: 승인된 리비전과 현재 헤드를 비교합니다. 서로 다르면 새로운 검사와 승인을 받아야 합니다.
• diff에 민감한 파일이나 생성된 파일이 포함됨: 모델에 내용을 보내기 전에 해당 파일을 필터링하거나 풀 리퀘스트를 사람에게 전달합니다.
• 검토자가 승인 대상을 파악하기 어려움: 요청에 대상 저장소, 리비전, 제안된 작업, 테스트 근거를 포함하고 작업 매개변수를 표시합니다.

간단한 배포 체크리스트

쓰기 작업을 활성화하기 전에 워크플로가 유효하지 않은 스키마를 거부하고, 재시도 횟수를 제한하며, 실패하거나 대기 중인 테스트에서 멈추고, 리비전 변경을 처리하고, 거부를 쓰기 작업이 없는 경로로 전달하는지 확인하세요. 샘플 데이터와 비프로덕션 저장소를 사용해 각 오류 분기를 테스트합니다. 처음에는 모든 병합에 승인을 요구하고, 팀에서 명확하고 문서화된 근거를 마련한 뒤에만 정책을 조정하세요.

안정적인 패턴은 간단합니다. 필요한 정보만 추출하고, 기계적으로 검증하며, 정확한 리비전을 기준으로 확인한 뒤, 중요한 저장소 작업은 사람이 승인하게 하세요. n8n의 승인 단계는 일시 중지 지점을 제공하지만, 워크플로 자체에도 스키마 검사, 재시도 규칙, 리비전 보호 장치가 필요합니다.

출처

• n8n: 도구 사용 시 휴먼 인 더 루프 — 승인 동작, 지원되는 검토 채널 예시, 도구 매개변수, 시스템 프롬프트 지침