<div align="center">
Pipewright
경량의 자체 호스팅형 CI/CD(지속적 통합) + 배포 + 운영(ops) 플랫폼입니다.
단일 정적 Go 바이너리(프론트엔드 내장, 런타임 종속성 없음)로 구성되어 있으며, 이 하나의 도구가 "CI + Ansible/Kamal + Portainer" 삼총사를 대체합니다.
Release
CI
License: MIT
English | 简体中文
</div>
Pipewright를 사용해야 하는 이유 (Why Pipewright)
주류 옵션들은 무겁거나(플러그인 다발이 붙은 Jenkins + JVM), 세 가지 도구의 조합입니다(Woodpecker/Drone + Ansible/Kamal + Portainer). Pipewright는 "지속적 통합(CI), 다중 서버 배포, 서버/컨테이너 운영(ops)" 기능을 하나의 정적 바이너리에 담았습니다. 다운로드하고 시작한 다음 브라우저를 열기만 하면 설치가 완료됩니다.
이 도구는 이후 해당 삼총사를 넘어 발전했습니다. HTTPS 도메인에 배포된 서비스를 게시하는 기능(nginx + certbot 단계)과 모든 풀 리퀘스트(pull request)에 자체 라이브 미리보기 URL을 제공하는 기능도 내장되어 있습니다.
| Pipewright | Jenkins | Drone + Ansible + Portainer |
|---|
| 단일 바이너리 배포 | ✅ | ❌ JVM + 플러그인 | ❌ 세 도구 조합 |
| ... | | | |
스크린샷 (Screenshots)
전역 개요(Global overview) — 프로젝트, 실행 성공률, 환경 배포 상태, 서버 상태 및 DORA 지표를 한 화면에서 확인할 수 있습니다:
Dashboard
시각적 파이프라인 오케스트레이션(Visual pipeline orchestration) — 두 단계(stage/job)로 구성된 DAG 캔버스입니다. 직렬 연결을 위한 수평 링크와 진정한 병렬 처리를 위한 수직 나란히 배치를 지원합니다. 매트릭스 빌드, 수동 승인 게이트, 사이드카 서비스, 후속 단계(post-stage steps)를 지원하며, 캔버스와 YAML 양방향 순환(round-trip)이 모두 가능합니다:
Pipeline canvas
실행 상세 정보(Run detail) — 스테이지 전환, 라이브 로그(SSE 푸시 + 히스토리 재생), 빌드 아티팩트 및 이미지 참조, 단계별 상태를 제공합니다:
Run detail
컨테이너 관리(Container management) — 호스트 전반에 걸친 컨테이너/이미지/Stack/볼륨/네트워크의 원스톱 관리를 제공하며, 라이프사이클 운영, 실시간 통계, 로그 및 인터랙티브 터미널을 지원합니다:
Container management
기능 개요 (Feature Overview)
• 🔐 보안 기반(Security foundation) — 단일 관리자 인증(single-admin auth) 지원 (argon2id + CSRF) · 암호화된 자격 증명 볼트(encrypted credential vault) 제공 (NaCl secretbox, 마스킹 표시, 절대 평문 아님) · Gitee / GitHub / GitLab / 자체 호스팅 인스턴스를 위한 OAuth 앱 온보딩 (액세스 토큰이 재사용 가능한 자격 증명으로 볼트에 바로 저장됨) · 추가 전용 감사(append-only audit) 기능 제공 (SQLite 트리거를 사용하여 UPDATE/DELETE를 강제 차단하며, 선택적 원격 싱크 지원) · 로그, 진단 및 알림 전반에 걸친 실행별 비밀 정보 마스킹(secret redaction).
• 🧩 프로젝트 및 파이프라인(Projects & pipelines) — 시각적 오케스트레이션 캔버스 제공 (스테이지 DAG + 스테이지 내 작업 레벨 DAG) · 매트릭스 빌드(matrix builds) 지원 · 수동 승인 게이트(manual approval gates) 기능 (서명된 링크를 통해 알림에서 직접 승인 가능) · 사이드카 서비스(sidecar services) 연결 (테스트를 위해 DB/Redis 연결) · 스테이지 when 조건 및 후속 단계(post-stage steps) 설정 · 타입 지정 실행 매개변수(typed run parameters) 지원 (열거형/부울/숫자, 트리거 시점에 검증됨) · 다양한 트리거: 웹훅(webhook), 브랜치→환경 매핑, 5필드 크론(cron), 그리고 상위→하위 파이프라인 체이닝 (깊이 및 경로 가드를 통한 루프 안전성 확보) · 프로젝트별 동시성 제한(concurrency caps)과 FIFO 큐잉 시스템 제공 · 파이프라인 템플릿, 변수 그룹 및 사용자 지정 노드의 재사용 라이브러리 제공 · 서버 권한 검증(server-authoritative validation).
• 📝 코드형 파이프라인(Pipeline as code) — 파이프라인 구조를 .pipewright.yml에 커밋하여 브랜치별로 진화시키며, 캔버스는 항상 사용 가능한 대체 수단임([아래 #pipeline-as-code-gitops 참조]).
-
🏗 격리된 빌드 및 아티팩트(Isolated builds & artifacts) — 컨테이너 내부의 버전 고정형 격리 빌드 지원 (docker/nerdctl/podman) · 로컬 베어-미러 레포 캐시 (증분 가져오기, 즉시 작업 공간 구성) · 브랜치 + lockfile 해시에 키가 지정된 빌드 의존성 캐싱 · 배포를 위한 jar/dist의 실제 바이트를 보관하는 콘텐츠 주소 지정 아티팩트 스토어 (단순한 플레이스홀더 참조가 아님) · 이미지 빌드 및 이미지 GC(Garbage Collection)가 적용된 프라이빗 레지스트리 푸시 기능 · 프로젝트별 선택적 원격 빌드 머신 지원 (빌드는 SSH를 통해 오프로드되며, 토큰은 제어 노드에 유지됨) · JUnit + Cobertura 테스트 보고서를 품질 게이트로 피딩하여 스테이지 실패 및 다운스트림 배포 차단 · 실시간 터미널 로그(SSE)와 히스토리 리플레이 기능 · 읽기 전용 코드 브라우징 (Monaco).
-
🚀 다중 서버 배포(Multi-server deployment) — SSH를 통한 에이전트리스 배포 · 헬스 게이팅(health gating) 지원 · 무정지 전환(zero-downtime cutover) 및 실패 롤백 기능 · 호스트 전반에 걸친 병렬 팬아웃(parallel fan-out) 및 가시적인 부분 실패 감지 · 명령어 스타일 배포 (아티팩트 없이 서비스 재시작 가능) · 최상위 객체로서의 환경(environments as first-class objects): 환경별 배포 타임라인, 현재 활성 버전, 그리고 마지막으로 완전히 성공한 배포로 돌아가는 원클릭 롤백 기능 · 환경 승격 체인 (dev→staging→prod) 지원 및 환경별 변수/시크릿 관리와 승인 게이트.
-
🌐 자동 HTTPS + 도메인 리버스 프록시(Auto HTTPS + domain reverse proxy) — 대상 호스트당 하나의 관리형 Caddy 컨테이너를 운영하며, 이는 컨테이너 운영과 동일한 SSH + docker 경로로 오케스트레이션됨 (Caddyfile 렌더링 → docker cp → 우아한 리로드). 인증서는 Let's Encrypt를 통해 HTTP-01 또는 **DNS-01 (Cloudflare / DNSPod / Alibaba Cloud DNS)**을 사용하여 와일드카드를 위해 자동으로 발급 및 갱신됨. 추가 기능: 다중 도메인 별칭, 경로 라우팅 (/api→A, /→B), 리다이렉트, 접근 제어 (기본 인증(basic auth), IP 허용/거부 CIDR), HSTS / 보안 헤더 / 압축, 활성 헬스 체크 실패에 따른 업스트림 로드 밸런싱, WebSocket / gRPC (h2c) / TCP 패스스루 (caddy-l4), 실제 443 핸드셰이크를 프로빙하는 인증서 대시보드, 원클릭 서브도메인 할당.
-
🔎 PR별 미리보기 환경(Per-PR preview environments) — PR 실행이 성공적으로 배포되면, 해당 PR은 자체 인증서와 경로를 가진 일회용 pr-<n>-<proj>.<base> 도메인을 자동으로 할당받습니다. 따라서 검토자는 단 하나의 링크만 열면 실제로 해당 PR이 구동되는 것을 확인할 수 있습니다. 이 기능은 PR별로 동일성을 유지하며(Idempotent), PR이 명확하게 닫히거나 병합된 경우에만 자동 회수됩니다.
-
📣 알림(Notifications) — WeCom / DingTalk / Lark (Feishu) / Slack / 이메일 / 사용자 지정 웹훅을 지원합니다. 세밀한 이벤트별 채널 라우팅, 템플릿 및 사용자 지정 변수 설정이 가능하며, 승인/상세 액션 버튼과 릴리스 요약 정보를 담은 풍부한 Lark 카드를 제공합니다. 또한 파이프라인 내에 알림 노드(in-pipeline notification nodes)를 추가할 수 있습니다.
-
🖥 서버 및 컨테이너 운영(Server & container ops) — CPU/메모리/디스크를 포함한 다중 호스트 상태 개요와 시계열 추세 차트를 제공합니다. 컨테이너, 이미지, Stacks, 볼륨, 네트워크 관리가 가능하며, 컨테이너 생성/검사/정리(prune) 기능을 지원합니다. 실시간 및 기록 서비스 로그 확인, 실시간 통계, 대화형 컨테이너 터미널, 웹 운영 터미널(호스트 셸, 전체 복사/붙여넣기 및 신호 지원)을 제공합니다. 또한 타이머 기반으로 실행되고, 냉각 시간 간격에 따라 중복을 제거하며, 경고를 알림 채널로 라우팅하는 사용자 지정 이상 감지 기능도 설정할 수 있습니다.
-
🤖 AI 지원 (선택 사항, 완전한 성능 저하 가능) — 사용자가 직접 Claude / OpenAI / Ollama 엔드포인트(API 키는 볼트에서 암호화)를 연결할 수 있습니다. 빌드 또는 배포 실패 시 자동 근본 원인 진단 기능을 제공하며, 👍/👎 피드백 루프와 정확도 통계가 포함됩니다. 레포지토리 분석을 통해 파이프라인 초안을 생성하거나, 성공 대비 실패 커밋 차이를 확인하고, 스크립트 위험 주석을 달아줍니다. 또한 자연어(natural-language)를 셸 명령어 또는 운영 터미널의 컨테이너 진단으로 변환하는 기능을 제공합니다. 핵심 CI/CD 경로는 이 기능들에 전혀 의존하지 않습니다 (NFR-10).
-
📈 메트릭(Metrics) — 네 가지 DORA 지표(배포 빈도 / 변경 사항에 대한 리드 타임 / 변경 실패율 / 평균 복구 시간)를 기본으로 제공하며, Elite/High/Medium/Low 성능 구간을 표시합니다.
-
🧹 시스템 관리 및 플랫폼(Housekeeping & platform) — 설정 가능한 실행 데이터 보존 스위퍼(run-data retention sweeper)를 제공합니다(기본적으로 비활성화되며 진행 중인 실행에는 절대 영향을 주지 않음). SQLite (순수 Go) 또는 MySQL을 지원하며, 8개 UI 언어(zh-CN / zh-TW / en / ja / ko / de / fr / es)를 포함하여 서버 측 API 오류 메시지 현지화 기능을 제공합니다.
-
🔄 업데이트 확인 및 원클릭 자체 업데이트(Update check + one-click self-update) — 설정(Settings) → 시스템에서 명시적으로 선택된 GitHub 또는 구성된 Gitee 소스를 검색하여 시맨틱 비교를 통해 최신 릴리스를 확인합니다. 바이너리 배포는 UI에서 원클릭으로 자동 업데이트할 수 있습니다(다운로드 + 체크섬 검증 + 원자적 교체 + 자체 재시작). 반면, Docker 배포의 경우 정확한 업그레이드 명령을 받습니다.
보안은 협상 불가합니다: 자격 증명은 암호문 형태(ciphertext)로만 저장되며, 명령어는 주입 공격에 대비하여 배열화되고, 외부 SSRF(Server-Side Request Forgery)는 차단하며, 로그는 마스킹됩니다.
설치 / 배포 (Install / Deploy)
세 가지 형태 중 하나를 선택하세요. 플랫폼 자체는 실행 시 종속성이 전혀 없는(Go/Node 불필요) 단일 정적 바이너리입니다.
Docker 전제 조건: 플랫폼 자체가 Docker에 의존하지는 않지만, '격리 빌드 / 컨테이너 배포(isolated builds / container deployment)'를 위해서는 Docker가 필요합니다(없으면 스텁 러너로 기능이 저하되어 실제 빌드를 수행할 수 없습니다). 콘솔/SSH 배포/알림 기능은 Docker가 필요하지 않습니다. 원클릭 스크립트는 Docker의 유무를 감지하고 누락된 경우 안내하며, Linux에서는 INSTALL_DOCKER=1을 설정하여 자동 설치(공식 get.docker.com 이용)할 수 있고, macOS에서는 Docker Desktop을 설치해야 합니다.
① 원클릭 스크립트 (Linux / macOS)
기본적으로 GitHub Releases에서 플랫폼용 정적 바이너리를 다운로드하여 /usr/local/bin에 설치합니다(체크섬 검증 + Docker 감지 포함). SOURCE=gitee를 사용하면 구성된 공식 Gitee 미러를 명시적으로 선택할 수 있습니다. 소스는 절대로 조용히 전환되지 않습니다:
curl -fsSL https://raw.githubusercontent.com/huangchengsir/pipewright/master/install.sh | sh
...
권장: systemd 서비스로 설치 (부팅 시 자동 시작 + 충돌 시 재시작 + 원클릭 자체 업데이트 가능; Linux, 루트 권한 필요). 이 스크립트는 마스터 키를 /etc/pipewright/master.key에 영구 저장하고, 데이터를 /var/lib/pipewright에 저장하며, 설정을 /etc/pipewright/pipewright.env에 작성합니다:
SETUP_SERVICE=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/huangchengsir/pipewright/master/install.sh)"
...
Gitee 바이너리 소스 (선택 사항): 프로젝트의 신뢰할 수 있는 출처 또는 검증된 코드 미러에서 동일한 install.sh를 얻습니다. Gitee 설치는 엄격한 릴리스/JSON 유효성 검사를 위해 추가적으로 Python 3.9 이상을 요구하며, GitHub 설치는 원래의 종속성을 유지합니다.
SOURCE=gitee PIPEWRIGHT_GITEE_RELEASE_REPO=owner/pipewright VERSION=vX.Y.Z \
...
Gitee 릴리스는 여섯 개의 원래 플랫폼 아카이브, checksums.txt, 그리고 최종 pipewright-release.json 완료 마커가 일관되게 게시된 후에만 설치 가능합니다. 사용 불가능하거나 부분적으로 동기화된 미러는 설치된 프로그램의 변경 없이 안전하게 실패합니다. 이 설치 프로그램은 미러를 생성하거나, 자격 증명을 얻거나, 지리적 위치를 조회하거나, 소스 간에 폴백(fall back)하지 않습니다. 새로 생성된 systemd 서비스의 경우, 구성된 미러 레포지토리와 초기 Gitee 소스 선택이 환경 파일에 작성되며, 기존 환경 파일은 보존됩니다.
Windows 사용자: Releases에서 .zip을 다운로드하세요.
② docker compose (자체 호스팅에 권장)
호스트 도커 소켓과 함께 Docker-CLI가 활성화된 Pipewright 컨테이너를 실행할 때, 툴체인 작업은 소스 워크스페이스를 작업별(per-job) 도커 볼륨에 복사하고 나중에 빌드 출력을 복구합니다. 공유되는 호스트 /tmp 마운트는 필요하지 않습니다. 네이티브 바이너리 빌드는 직접적인 워크스페이스 마운트를 유지합니다. 표준 distroless 이미지는 로컬 빌드를 위해 여전히 Docker CLI가 활성화된 이미지 또는 네이티브 설치를 필요로 합니다. 도커 소켓을 마운트하는 것은 호스트 수준의 제어권을 부여하므로, 신뢰할 수 있는 환경에서만 수행해야 합니다.
curl -fsSLO https://raw.githubusercontent.com/huangchengsir/pipewright/master/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/huangchengsir/pipewright/master/.env.example
cp .env.example .env
...
③ docker run (가장 빠른 테스트)
docker run -d -p 8080:8080 -v pipewright-data:/data \
-e PIPEWRIGHT_ADMIN_PASSWORD=change-me \
-e PIPEWRIGHT_MASTER_KEY=$(openssl rand -base64 32) \
...
소스에서 빌드하기
