GitHub Repository는 에이전트의 워크스페이스다

n8n을 오케스트레이션 레이어로 연결하면 무슨 일이 벌어지는가

에이전트에게 워크스페이스란 무엇인가

에이전트가 일을 한다는 건 어딘가에 상태를 쌓는다는 뜻이다. 무엇을 했는지, 무엇이 바뀌었는지, 다음에 무엇을 해야 하는지. 이 상태가 저장되는 곳이 워크스페이스다.

GitHub Repository는 그 조건을 정확히 만족한다.

코드와 설정이 저장된다 — 에이전트가 수행할 작업의 명세
변경 이력이 남는다 — 커밋 단위로 무엇이 언제 바뀌었는지 추적
이벤트가 발생한다 — push, PR, issue, merge가 곧 상태 전이
브랜치로 작업이 분리된다 — 에이전트별 실험 공간

사람이 코드를 짜는 공간이라서 GitHub를 쓰는 게 아니다. 상태가 기록되고, 이벤트가 발생하고, 작업 단위가 명확하게 분리되기 때문에 에이전트의 워크스페이스로 적합하다.

GitHub Actions는 이 워크스페이스에 달린 이벤트 리스너다. 저장소에서 뭔가 일어나면 자동으로 반응한다.

Repository 상태 변화 (push, PR, issue, schedule)
    ↓
GitHub Actions 트리거
    ↓
작업 실행 (테스트, 빌드, 배포, 외부 신호 발송)

에이전트 관점에서 보면: 워크스페이스에 변화가 생기면 다음 단계가 자동으로 시작된다.

n8n은 오케스트레이션 레이어다

에이전트 하나가 모든 걸 할 수는 없다. 실제 시스템에서는 여러 에이전트, 여러 서비스, 여러 팀이 함께 움직인다. 누군가는 이것들을 조율해야 한다.

n8n이 그 역할이다.

n8n은 단순히 "앱을 연결하는 도구"가 아니다. 정확히는 조건을 판단하고, 경로를 결정하고, 여러 시스템에 작업을 배분하는 레이어다. 워크플로우 안에서 분기하고, 기다리고, 재시도하고, 에러를 핸들링한다. 이건 오케스트레이션이다.

GitHub Repository가 워크스페이스라면, n8n은 워크스페이스 바깥에 있는 조율 허브다.

GitHub (워크스페이스)
  ↕ 웹훅
n8n (오케스트레이션 레이어)
  ↓    ↓    ↓
슬랙  노션  다른 에이전트

n8n이 받을 수 있는 신호는 GitHub뿐이 아니다. 슬랙 메시지, 이메일, 외부 API, 타이머, 다른 에이전트의 완료 신호. 그것들을 모아서 다음 행동을 결정한다.

웹훅이 둘을 연결한다

GitHub Actions와 n8n은 웹훅으로 대화한다. 웹훅은 "이런 일이 생겼다"는 신호를 HTTP 요청으로 보내는 방식이다.

방향 1: 워크스페이스 → 오케스트레이터

GitHub Actions가 n8n에 신호를 보낸다. 워크스페이스에서 일어난 일을 오케스트레이터에게 알리는 방향이다.

# .github/workflows/notify.yml
on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: n8n에 신호 발송
        run: |
          curl -X POST ${{ secrets.N8N_WEBHOOK_URL }} \
            -H "Content-Type: application/json" \
            -d "{
              \"event\": \"push\",
              \"repo\": \"${{ github.repository }}\",
              \"actor\": \"${{ github.actor }}\",
              \"commit\": \"${{ github.sha }}\"
            }"

n8n은 이 신호를 받아서 무엇을 할지 결정한다. 슬랙에 알릴지, 노션에 기록할지, 다른 에이전트를 깨울지.

방향 2: 오케스트레이터 → 워크스페이스

역방향도 가능하다. n8n이 GitHub에 신호를 보내서 Actions를 트리거한다. repository_dispatch API를 쓴다.

# n8n HTTP Request 노드에서
POST https://api.github.com/repos/{owner}/{repo}/dispatches
{
  "event_type": "deploy-staging",
  "client_payload": { "env": "staging", "version": "1.2.3" }
}

이 구조에서는 n8n이 GitHub Repository를 제어한다. 외부 조건이 만족되면(예: QA 승인, 특정 시간, 다른 서비스의 완료 신호) n8n이 GitHub에 배포를 지시한다.

양방향 루프

두 방향을 합치면 루프가 만들어진다.

n8n이 deploy 신호 발송
    ↓
GitHub Actions 배포 실행
    ↓
완료 후 n8n에 결과 POST
    ↓
n8n이 결과 판단 → 다음 단계 결정

오케스트레이터가 워크스페이스에 작업을 시키고, 워크스페이스가 완료 신호를 오케스트레이터에게 돌려보내는 구조다. 에이전트 시스템에서 흔히 말하는 실행-관찰-판단 루프와 같은 패턴이다.

이 구조로 할 수 있는 것

다중 저장소 조율

프로젝트가 여러 Repository로 나뉘어 있을 때, n8n이 조율 허브가 된다. repo-A가 완료되면 n8n이 감지하고, repo-B의 Actions를 트리거한다. 각 저장소는 자신의 작업만 하면 된다. 조율은 n8n이.

repo-A: 빌드 완료 → n8n에 신호
    ↓
n8n: repo-B에 테스트 트리거
    ↓
repo-B: 테스트 완료 → n8n에 신호
    ↓
n8n: repo-C에 배포 트리거

외부 조건 기반 실행

GitHub 이벤트가 아니라 외부 조건이 워크스페이스를 움직이게 하고 싶을 때. 슬랙에서 특정 메시지가 올 때, 노션 태스크 상태가 바뀔 때, 정해진 시간이 됐을 때. n8n이 그 신호를 받아서 Actions를 트리거한다.

에러 핸들링과 재시도

Actions가 실패했을 때 n8n이 감지하고 재시도 로직을 처리할 수 있다. 혹은 실패를 감지해서 담당자에게 DM을 보내거나, 롤백 Actions를 트리거한다.

보안: 신호의 출처를 검증한다

n8n Webhook URL이 공개되면 누구든 워크플로우를 트리거할 수 있다. GitHub는 보내는 모든 요청에 HMAC-SHA256 서명을 붙인다. n8n에서 이 서명을 검증하면 GitHub에서 온 요청만 통과시킬 수 있다.

GitHub → [x-hub-signature-256 헤더 포함] → n8n Webhook
                                               ↓
                                    Function 노드에서 서명 검증
                                               ↓
                                    통과 → 워크플로우 진행
                                    실패 → 즉시 중단

Secrets는 GitHub 저장소 설정에 암호화 저장한다. workflow YAML에는 ${{ secrets.N8N_WEBHOOK_URL }} 같은 참조만 남는다. URL 자체는 코드베이스 어디에도 노출되지 않는다.

인프라로서의 GitHub + n8n

에이전트 시스템을 설계할 때 두 가지 레이어가 필요하다.

하나는 작업이 실행되는 공간. 상태가 저장되고, 이력이 남고, 작업 단위가 명확하게 분리되는 곳. GitHub Repository가 이 역할을 한다.

다른 하나는 작업을 조율하는 레이어. 무엇을 언제 실행할지, 어느 시스템에 무엇을 시킬지, 결과를 어떻게 처리할지를 결정하는 곳. n8n이 이 역할을 한다.

GitHub Actions는 두 레이어를 잇는 이벤트 브리지다. 워크스페이스에서 일어난 일을 오케스트레이터에게 알리고, 오케스트레이터의 지시를 받아서 워크스페이스에서 실행한다.

이 세 가지를 갖추면, 코드를 저장하는 것 자체가 자동화 파이프라인의 시작점이 된다.

기술 상세: [[2026-05-14_GitHub-Actions-웹훅-n8n-연동-기술리포트]]