n8n으로 개발 알림 자동화 — GitHub·서버·Telegram 연결

n8n이란? 개발팀을 위한 오픈소스 워크플로우 자동화

개발을 하다 보면 반복적으로 처리해야 하는 알림 작업들이 많습니다. GitHub에 새 PR이 열렸을 때, 서버에서 에러가 발생했을 때, 배포가 완료됐을 때 — 이런 이벤트를 팀에게 실시간으로 전달하려면 어떻게 해야 할까요? n8n은 이런 문제를 노코드/로우코드로 해결해주는 오픈소스 워크플로우 자동화 도구입니다.

n8n은 Zapier나 Make(구 Integromat)와 비슷하지만, 셀프 호스팅이 가능하고 소스코드가 공개되어 있습니다. 민감한 API 키와 서버 정보를 외부 SaaS에 넘기지 않아도 되는 것이 큰 장점입니다. 이번 글에서는 n8n을 설치하고 GitHub 이벤트, 서버 헬스체크, Telegram 알림을 연결하는 실전 워크플로우를 구성해 보겠습니다.

n8n 설치 — Docker로 5분 만에 띄우기

n8n은 Docker를 쓰면 가장 빠르게 설치할 수 있습니다. AWS Lightsail이나 로컬 환경 어디서든 아래 명령어 하나로 실행됩니다.

# Docker로 n8n 실행 (데이터 영속성 포함)
docker run -d   --name n8n   -p 5678:5678   -v ~/.n8n:/home/node/.n8n   -e N8N_BASIC_AUTH_ACTIVE=true   -e N8N_BASIC_AUTH_USER=admin   -e N8N_BASIC_AUTH_PASSWORD=your_password   -e WEBHOOK_URL=https://your-domain.com/   --restart unless-stopped   n8nio/n8n

# 실행 확인
docker ps | grep n8n
# → 5678 포트로 n8n 웹 UI 접근 가능

설치 후 http://localhost:5678에 접속하면 n8n의 비주얼 워크플로우 에디터가 열립니다. 처음 접속 시 계정을 생성하고 나면 바로 워크플로우를 만들 수 있습니다.

Nginx 리버스 프록시 설정

# /etc/nginx/sites-available/n8n.conf
server {
    listen 80;
    server_name n8n.yourdomain.com;

    location / {
        proxy_pass http://localhost:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
    }
}

# SSL 적용
certbot --nginx -d n8n.yourdomain.com

워크플로우 1 — GitHub 이벤트를 Telegram으로 알림

가장 자주 쓰는 패턴입니다. GitHub Webhook을 n8n이 받아서 Telegram으로 포맷된 메시지를 전송합니다. PR 생성, 코드 리뷰 요청, 이슈 오픈 등 다양한 이벤트에 대응할 수 있습니다. n8n에서 Webhook 노드를 추가하고 URL을 복사한 뒤 GitHub 레포지토리 Settings → Webhooks → Add webhook에 등록합니다.

// n8n Function 노드 — GitHub 이벤트 → Telegram 메시지 포맷
const event = $json.headers['x-github-event'];
const payload = $json.body;

let message = '';

if (event === 'pull_request') {
  const action = payload.action;
  const pr = payload.pull_request;
  const emoji = action === 'opened' ? '🟢' : action === 'closed' ? '🔴' : '🔄';
  message = `${emoji} *PR ${action.toUpperCase()}*
` +
    `📌 ${pr.title}
👤 ${pr.user.login}
🔗 ${pr.html_url}`;

} else if (event === 'push') {
  const commits = payload.commits?.length || 0;
  const branch = payload.ref.replace('refs/heads/', '');
  message = `📦 *PUSH — ${branch}*
` +
    `📝 ${commits}개 커밋
👤 ${payload.pusher.name}
` +
    `💬 ${payload.head_commit?.message || ''}`;

} else if (event === 'issues') {
  const issue = payload.issue;
  message = `🐛 *ISSUE ${payload.action.toUpperCase()}*
` +
    `📌 ${issue.title}
👤 ${issue.user.login}
🔗 ${issue.html_url}`;
}

return [{ json: { message, chat_id: 'YOUR_TELEGRAM_CHAT_ID' } }];

위 Function 노드 다음에 Telegram 노드를 연결하고 Bot Token과 Chat ID를 설정하면 됩니다. n8n의 Credentials 기능을 사용하면 API 키를 안전하게 저장하고 여러 워크플로우에서 재사용할 수 있습니다.

워크플로우 2 — 서버 에러 감지 및 자동 알림

FastAPI 서버에서 500 에러가 발생하거나 응답 지연이 생겼을 때 즉시 알림을 받는 워크플로우입니다. n8n의 Schedule 트리거(5분마다)와 HTTP Request 노드를 조합하고, IF 노드로 200 이외의 응답이나 2초 초과 시 Telegram 알림을 전송합니다.

# FastAPI 헬스체크 엔드포인트
from fastapi import FastAPI
from sqlalchemy import text
from app.database import async_session
import time

app = FastAPI()

@app.get("/health")
async def health_check():
    start = time.time()
    try:
        async with async_session() as session:
            await session.execute(text("SELECT 1"))
        db_status = "ok"
    except Exception as exc:
        db_status = f"error: {str(exc)}"
    
    response_time = round((time.time() - start) * 1000, 2)
    return {
        "status": "ok" if db_status == "ok" else "error",
        "db": db_status,
        "response_time_ms": response_time,
        "timestamp": time.time()
    }

워크플로우 3 — GitHub Actions 배포 완료 보고

GitHub Actions에서 배포가 완료되면 n8n Webhook을 호출하고, n8n은 이를 Telegram 채널에 보고하는 패턴입니다. 배포 성공/실패 여부와 커밋 정보를 한 번에 확인할 수 있습니다.

# .github/workflows/deploy.yml 일부
      - name: Notify on success
        if: success()
        run: |
          curl -X POST "https://n8n.yourdomain.com/webhook/deploy-notify"             -H "Content-Type: application/json"             -d "{
              "status": "success",
              "branch": "$GITHUB_REF_NAME",
              "commit": "$GITHUB_SHA",
              "actor": "$GITHUB_ACTOR"
            }"
      
      - name: Notify on failure
        if: failure()
        run: |
          curl -X POST "https://n8n.yourdomain.com/webhook/deploy-notify"             -H "Content-Type: application/json"             -d "{
              "status": "failure",
              "branch": "$GITHUB_REF_NAME",
              "actor": "$GITHUB_ACTOR"
            }"

n8n 운영 팁

장기 운영 시 실행 이력이 쌓여 DB가 느려질 수 있습니다. EXECUTIONS_DATA_PRUNE=true와 EXECUTIONS_DATA_MAX_AGE=720(30일) 환경변수로 자동 정리를 설정하세요. 또한 Error Trigger 노드로 구성된 별도 워크플로우를 만들어두면 모든 워크플로우의 실패를 한 곳에서 감지하고 알림으로 받을 수 있습니다.

n8n 데이터 저장소로 기본 SQLite 대신 PostgreSQL을 사용하면 성능과 안정성이 크게 향상됩니다. 이미 FastAPI 프로젝트에서 PostgreSQL을 사용하고 있다면 별도 DB 인스턴스 없이 n8n 전용 스키마를 만들어 함께 운영할 수 있습니다.

마무리

n8n 워크플로우를 구성하고 나면 Telegram 하나로 전체 시스템 상태를 실시간으로 파악할 수 있습니다. GitHub 이벤트, 서버 헬스, 배포 상태가 통합 알림으로 들어오면 무언가 잘못됐을 때 즉시 대응할 수 있고, 불필요한 수동 확인 작업이 크게 줄어듭니다. 초기 설정에 2~3시간을 투자하면 이후 수십 시간의 반복 작업을 절약할 수 있습니다.

코드벤터는 글로벌 개발 협력 네트워크를 기반으로 자동화, 인프라 최적화, 풀스택 서비스 개발 역량을 결합해 클라이언트의 개발 생산성 향상을 지원하고 있습니다. n8n처럼 실무에서 검증된 오픈소스 도구를 적극 활용해 더 나은 개발 환경을 만들어가고 있습니다.