| name | cicd |
| description | CI/CD 파이프라인 구성 AI 협업 -- DevOps 엔지니어가 Jenkins/GitHub Actions CI + ArgoCD CD 파이프라인 구축 |
| type | orchestrator |
| user-invocable | true |
CI/CD
[NPD CI/CD 활성화]
목표
DevOps 엔지니어가 CI/CD 파이프라인 코드(Jenkinsfile, GitHub Actions Workflow, Kustomize 매니페스트)를 생성하고,
ArgoCD GitOps 방식으로 CD를 분리하는 파이프라인을 구축한다.
활성화 조건
사용자가 /npd:cicd 호출 시 또는 "CICD 시작", "CI/CD 구성", "파이프라인 작성", "자동 배포" 키워드 감지 시.
주의사항: 중간 단계부터 시작할 때도 진행 모드 결정 + 환경 정보 수집을 위해 Phase 0은 항상 수행해야 합니다.
선행 조건
/npd:create 완료 (프로젝트 디렉토리 및 AGENTS.md 존재)/npd:deploy Phase 5 (K8s 배포)까지 완료된 상태 (기존 K8s 매니페스트 deployment/k8s/ 존재)- CI/CD 도구 설치: Phase 1에서 자동 설치 또는 사전 설치 완료 (CI 도구, SonarQube, ArgoCD, Image Registry Credential)
작업 환경 변수 로드
AGENTS.md 파일에서 ## 환경변수 섹션의 환경변수 로딩.
로딩 실패 시 사용자에게 /npd:create을 먼저 수행하라고 안내하고 종료.
에이전트 호출 규칙
| 에이전트 | FQN |
|---|
| devops-engineer | npd:devops-engineer:devops-engineer |
프롬프트 조립
{NPD_PLUGIN_DIR}/resources/guides/combine-prompt.md에 따라
AGENT.md + agentcard.yaml + tools.yaml 합치기Agent(subagent_type=FQN, model=tier_mapping 결과, prompt=조립된 프롬프트) 호출- tier → 모델 매핑은
{NPD_PLUGIN_DIR}/gateway/runtime-mapping.yaml 참조
서브 에이전트 호출
워크플로우 단계에 Agent: {agent-name}이 명시된 경우,
메인 에이전트는 해당 단계를 직접 수행하지 않고, {NPD_PLUGIN_DIR}/resources/guides/call-subagent.md에 따라 서브 에이젼트 호출
변수명 규약
가이드 파일에서 사용하는 서비스명 관련 플레이스홀더 규약:
| 플레이스홀더 | 출처 | 설명 |
|---|
{SYSTEM_NAME} | [실행정보] | 백엔드 시스템명 (settings.gradle의 rootProject.name) |
{FRONTEND_SERVICE} | [실행정보] | 프론트엔드 서비스명 (package.json의 name). package.json 감지 시에만 포함 |
{AI_SERVICE} | [실행정보] | AI 서비스명 (pyproject.toml의 [tool.poetry] name). pyproject.toml 감지 시에만 포함 |
{SERVICE_NAMES} | settings.gradle 파싱 | 백엔드 서비스명 목록 (include 'common' 하위). [실행정보]에 포함되지 않으며, 에이전트가 settings.gradle에서 직접 파싱 |
{서비스명1}, {서비스명2} ... | {SERVICE_NAMES}의 개별 항목 | 가이드 내 예시에서 사용하는 반복 표기 |
{PYTHON_VERSION} | pyproject.toml 파싱 | Python 버전. [tool.poetry.dependencies]의 python 필드. 미감지 시 3.11 |
주의: 가이드 파일마다 {SERVICE_NAME1} (밑줄 없음), {SERVICE_NAME_1} (밑줄 있음), {서비스명1} (한글), {SERVICE_NAMEN} (N번째를 의미하는 말줄임) 등이 혼용됩니다. 모두 동일하게 {SERVICE_NAMES}의 개별 항목을 의미합니다.
클라우드별 차이 처리 안내
- Jenkins, GitHub Actions 모두 클라우드 무관하게 동일 가이드 사용 (가이드 내 조건부 섹션으로 처리)
- 클라우드별 차이는 registry login 인증 방식뿐이며,
[실행정보]의 CLOUD 값에 따라 가이드 내 조건부 섹션 적용
{IMG_REG}/{IMG_ORG} 변수로 레지스트리 URL을 추상화하므로 build/push/manifest 업데이트 로직은 동일
가이드 선택 매트릭스
CI 도구에 따라 참조할 가이드 파일이 결정된다. 클라우드별 분기 불필요 — CI/CD 분리 후 클라우드별 차이는 registry login 1개 step뿐이므로, 가이드 내 조건부 섹션으로 처리한다. 모든 가이드는 {NPD_PLUGIN_DIR}/resources/guides/cicd/ 경로에 위치한다.
| CI 도구 | 백엔드 가이드 | 프론트엔드 가이드 | AI 서비스 가이드 |
|---|
| Jenkins | deploy-jenkins-cicd-back.md | deploy-jenkins-cicd-front.md | deploy-jenkins-cicd-ai.md |
| GitHub Actions | deploy-actions-cicd-back.md | deploy-actions-cicd-front.md | deploy-actions-cicd-ai.md |
Phase 1 가이드: CI/CD 도구 사전 설치는 cicd-pre-setup.md 가이드를 참조한다 (CI 도구·클라우드 무관 공통).
CI/CD 분리 핵심 원칙
CI의 책임: 빌드 → 이미지 푸시 → manifest repository의 YAML에서 image tag만 변경
CD의 책임: ArgoCD가 manifest repository 변경을 감지하여 K8s에 자동 배포
CI에서 kubectl apply 절대 금지: CI 파이프라인은 K8s에 직접 배포하지 않는다.
기존 CI 가이드(deploy-jenkins-cicd-.md, deploy-actions-cicd-.md)의 빌드·푸시 부분과
ArgoCD 가이드(deploy-argocd-cicd.md)의 manifest repo 업데이트 부분을 하나의 파이프라인에 결합하여
처음부터 CI/CD가 분리된 파이프라인을 생성한다.
별도의 _ArgoCD 변환 단계는 불필요하다.
진행상황 업데이트 및 재개
{PROJECT_DIR}/AGENTS.md에 각 Phase의 Step 완료 시 저장. 최종 완료 시 Done으로 표기.
## 워크플로우 진행상황
### cicd
- 진행 모드: {선택값}
- CI_TOOL: {Jenkins|GitHubActions} (Phase 0 / Step 3에서 기록)
- CLOUD: {AWS|Azure|GCP} (`### deploy`에서 복원)
- 레지스트리유형: {DockerHub|ECR|ACR|GCR}
- AI_SERVICE: {값}
- MANIFEST_REPO_URL: {값} (Phase 0 / Step 6에서 기록)
- VM_HOST: {값}
- ENVIRONMENTS: {값} (Phase 0 / Step 7에서 기록)
- K8S_CLUSTER, K8S_NAMESPACE: {값}
- 마지막 완료 Phase/Step: {Phase X / Step Y}
{PROJECT_DIR}/AGENTS.md의 ## 워크플로우 진행상황 > ### cicd에 진행상황 정보가 있는 경우 마지막 완료 Step 이후부터 자동 재개.
### deploy 섹션도 함께 읽어 사전 바인딩 적용 (Phase 0 / Step 4 규칙).
워크플로우
개요
Phase 0: 사전 체크 + 모드 선택 + 정보 수집 (8 Step)
↓
Phase 1: CI/CD 도구 사전 설정 (사전작업 + 병렬 도구 설치 + Nginx + 수동 확인)
↓
Phase 2: 매니페스트 레포지토리 + ArgoCD 구성 (Git 크리덴셜 + ArgoCD 구성 + Push + CI 도구별 추가 정보)
↓
Phase 3: CI/CD 파이프라인 작성 (백엔드·프론트엔드·AI + Push)
↓
Phase 4: 완료 보고
Phase 0: 사전 체크 + 모드 선택 + 정보 수집
- GUIDE:
{NPD_PLUGIN_DIR}/resources/guides/cicd/phase0-presetup.md ← 필수 로드
- TASK: 위 GUIDE의 8개 Step 절차에 따라 사용자 입력 사전 수집 +
[실행정보] 조립 (Step 8은 cicd-runinfo-templates.md 참조)
- EXPECTED OUTCOME:
[실행정보] 블록 (CI 도구 + Cloud 조합별 7가지 템플릿 중 하나) + AGENTS.md ### cicd 진행상황 갱신
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 1. hosts 파일 등록 확인
CI/CD 도구 웹 UI 접속용 hosts 파일 등록 확인.
Step 2. 진행 모드 선택
단계별 승인/자동 진행 선택. 자동 진행 시 Phase 1~3 실행 중 ASK_USER 호출 자제.
(중요) 자동 진행 시 사용자에게 진행에 필요한 정보를 한꺼번에 요청. AskUserQuestion 사용하지 않고 대화창으로 질문
Step 3. CI 도구 선택
Jenkins / GitHub Actions 선택.
Step 4. deploy 환경 정보 복원
AGENTS.md > ### deploy에서 CLOUD/레지스트리/VM_HOST/K8S 변수 바인딩.
Step 5. 프로젝트 유형 감지 및 사전 검증
백/프/AI 자동 감지 + K8s 매니페스트 존재 검증 + 프로젝트명 자동 감지.
Step 6. 매니페스트 레포지토리 URL 결정
{org}/{SYSTEM_NAME}-manifest.git 자동 결정.
Step 7. 배포 환경 선택
ENVIRONMENTS = dev/staging/prod (multi-select).
Step 8. [실행정보] 조립
- GUIDE:
{NPD_PLUGIN_DIR}/resources/guides/cicd/cicd-runinfo-templates.md ← 필수 로드
- CI 도구 + 레지스트리 조합에 따라 7가지 템플릿 중 1개 조립 + AGENTS.md 상태 기록.
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Phase 1: CI/CD 도구 사전 설정 → Agent: devops-engineer
- GUIDE:
{NPD_PLUGIN_DIR}/resources/guides/cicd/cicd-pre-setup.md ← 필수 로드
- CONTEXT: Phase 0 / Step 8에서 조립된
[실행정보] 블록 포함
- TASK: 가이드를 참조하여 클라우드별 사전작업 수행 및 CI/CD 도구(Jenkins/SonarQube/ArgoCD) 설치
- 실행 조건: 항상 수행. 이미 설치된 도구는 자동 건너뜀 (idempotent)
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 1. 사전작업 + 매니페스트 레포 생성 (순차)
- 클라우드별 사전작업 (StorageClass, IngressClass, NodePool)
- 매니페스트 레포지토리 생성 (
gh repo create {org}/{SYSTEM_NAME}-manifest --private, 이미 존재 시 건너뜀)
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 2. 도구 설치 (병렬)
Step 1 완료 후, 아래 도구를 병렬로 설치 (각각 독립 에이전트 호출).
| Sub-step | 가이드 섹션 | 설치 내용 |
|---|
| Step 2-1 | Phase 2 | Jenkins Helm 설치 + RBAC (CI_TOOL == Jenkins인 경우) |
| Step 2-2 | Phase 3 | SonarQube Helm 설치 + affinity 패치 + scale 재시작 + 백엔드 단위테스트 실행·에러 해결 |
| Step 2-3 | Phase 4 | ArgoCD Helm 설치 + --insecure 검증 |
Jenkins와 ArgoCD는 cicd NodePool을, SonarQube는 sonarqube NodePool을 사용.
NodePool 리밋(cpu:16, mem:64Gi)이 충분하므로 동시 스케줄링 가능.
CI_TOOL == GitHubActions이면 Step 2-1(Jenkins)는 건너뜀 (Step 2-2·2-3 2개만 병렬).
Step 2-1. Jenkins Helm 설치 + RBAC → Agent: devops-engineer
- 가이드의 Phase 2 섹션 참조
- CI_TOOL == Jenkins인 경우만 수행. GitHub Actions이면 건너뜀.
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 2-2. SonarQube Helm 설치 + 설정 → Agent: devops-engineer
- 가이드의 Phase 3 섹션 참조
- affinity 패치 + scale 재시작 + 백엔드 단위테스트 실행·에러 해결 포함
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 2-3. ArgoCD Helm 설치 + 검증 → Agent: devops-engineer
- 가이드의 Phase 4 섹션 참조
- --insecure 검증 포함
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 3. Nginx 프록시 + 보고서 (순차) → Agent: devops-engineer
Step 2 (병렬 도구 설치) 완료 후:
- Nginx 프록시 설정 (SSH로 Web Server VM에 자동 설정)
- 프록시 연결 검증 (curl)
docs/cicd/cicd-pre-setup-report.md 결과 보고서 작성 (접속정보 + 암호 포함)
EXPECTED OUTCOME (Phase 1 / Step 1~3 종합):
- 클라우드별 사전작업 완료 (StorageClass, NodePool 등)
- Jenkins Pod 정상 실행 (CI_TOOL == Jenkins인 경우)
- SonarQube Pod 정상 실행
- 백엔드 단위테스트 통과 및 JaCoCo 리포트 생성 확인 (SonarQube 설정 후)
- ArgoCD Pod 정상 실행
- Nginx 프록시 설정 완료 (SSH 자동,
nginx -t 성공, curl 검증 통과)
- 수동 후속 작업 안내 메시지 출력
docs/cicd/cicd-pre-setup-report.md 결과 보고서 작성 (프로젝트 루트)
수동 후속 작업 안내 (에이전트가 자동 설치 완료 후, 사용자에게 안내):
- hosts 파일 등록
- Jenkins 플러그인 설치 및 K8s Cloud 연결
- SonarQube Token/Webhook/Quality Gate 설정
- Image Registry / DockerHub Credential 등록
- (GitHub Actions 선택 시) Repository Secrets/Variables 등록
수동 안내 시 setup-cicd-tools.md 원본 가이드 링크를 참조 제공.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 4. 수동 설정 완료 확인 (Phase 2 시작 전)
Step 1~3 자동 설치 완료 후 (또는 "이미 설치 완료" 선택 시), Phase 2 진행 전에
setup-cicd-tools.md의 수동 후속 설정 완료 여부를 확인한다.
{"title":"수동 설정 완료 확인","questions":[
{"question":"CI/CD 도구의 수동 후속 설정을 완료했나요?\n\n- hosts 파일 등록\n- Jenkins 플러그인 설치 및 K8s Cloud 연결 (Jenkins 선택 시)\n- SonarQube Token/Webhook/Quality Gate 설정\n- Image Registry / DockerHub Credential 등록 (Jenkins 선택 시)\n- GitHub Actions Secrets/Variables 등록 (GitHub Actions 선택 시)\n\n미완료 시 아래 가이드를 참조하세요:\nhttps://github.com/unicorn-plugins/npd/blob/main/resources/references/setup-cicd-tools.md","type":"radio","options":["모두 완료","아직 미완료"]}
]}
- "모두 완료" 선택 시: Phase 2 진행
- "아직 미완료" 선택 시: 가이드 링크를 다시 안내하고 완료 대기
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Phase 2: 매니페스트 레포지토리 + ArgoCD 구성 → Agent: devops-engineer
- GUIDE:
{NPD_PLUGIN_DIR}/resources/guides/cicd/phase2-argocd-setup.md ← 필수 로드
(참조: {NPD_PLUGIN_DIR}/resources/guides/cicd/deploy-argocd-cicd.md)
- TASK: 위 GUIDE의 4개 Step에 따라 Git 크리덴셜 수집 → ArgoCD 구성 → 매니페스트 레포 Push → CI 도구별 추가 정보 수집
- EXPECTED OUTCOME: 매니페스트 레포지토리 구조 + ArgoCD Application YAML + AGENTS.md
### cicd > [실행정보] 보완
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Kustomize 파일 관리 원칙: Phase 2에서 매니페스트 레포지토리에 Kustomize 파일을 생성합니다 (ArgoCD가 감시하는 "라이브" 매니페스트). Phase 3에서는 CI/CD 파이프라인 파일(Jenkinsfile/GitHub Actions workflow)을 생성하며, 파이프라인의 마지막 단계에서 매니페스트 레포의 image tag만 업데이트합니다.
Step 1. Git 크리덴셜 사전 수집 (에이전트 호출 전)
ArgoCD Private 레포 인증용 GIT_USERNAME/GIT_TOKEN 수집.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 2. ArgoCD 구성 (TASK)
Kustomize base/overlays + ArgoCD Application YAML 생성·등록.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 3. 매니페스트 레포지토리 Push (POST_ACTION)
ArgoCD가 변경 감지하도록 원격 레포에 push.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 4. CI 도구별 추가 정보 수집 + [실행정보] 보완
Jenkins: JENKINS_CLOUD_NAME, JENKINS_GIT_CREDENTIALS / GitHub Actions: 고정값 사용.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Phase 3: CI/CD 파이프라인 작성 → Agent: devops-engineer
- GUIDE:
{NPD_PLUGIN_DIR}/resources/guides/cicd/phase3-pipeline-creation.md ← 필수 로드
(참조: 위 ## 가이드 선택 매트릭스의 CI 도구별 가이드 + deploy-argocd-cicd.md manifest 업데이트 스크립트)
- TASK: 위 GUIDE의 4개 Step에 따라 백엔드·프론트엔드·AI 서비스 파이프라인 작성 (Phase 0 / Step 5에서 감지된 유형만) + 소스 레포 Push
- EXPECTED OUTCOME: CI/CD 파이프라인 파일 (Jenkinsfile 또는 GitHub Actions workflow) + 결과 보고서
- POST-ACTION:
{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 1. 백엔드 CI/CD 파이프라인 작성
가이드의 Jenkinsfile 템플릿 그대로 사용 + {플레이스홀더} 치환 + Job 생성·빌드·검증.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 2. 프론트엔드 CI/CD 파이프라인 작성
프론트엔드 가이드 + ArgoCD manifest 업데이트 스크립트.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 3. AI 서비스 CI/CD 파이프라인 작성
AI 가이드 + ArgoCD manifest 업데이트 스크립트.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 4. 소스 레포지토리 Push (POST_ACTION)
Step 1~3 산출물을 소스 레포에 push (Jenkins가 파이프라인 파일에 접근 가능하도록).
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Phase 4: 완료 보고
스킬 레벨에서 직접 수행 (에이전트 호출 없음).
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
Step 1. 완료 보고
## CI/CD 파이프라인 구성 완료
### 환경 정보
- CI 도구: {Jenkins / GitHub Actions}
- CD 도구: ArgoCD (GitOps)
- Cloud: {AWS / Azure / GCP}
- K8s 클러스터: {클러스터명}
### Phase 1: CI/CD 도구 사전 설정 산출물
- 클라우드 사전작업: {완료/건너뜀}
- Jenkins: {설치 완료/건너뜀} (CI_TOOL에 따라)
- SonarQube: {설치 완료/건너뜀}
- ArgoCD: {설치 완료/건너뜀}
- Nginx 프록시: {설정 완료} (VM: {VM_HOST})
- 사전 설정 보고서: `docs/cicd/cicd-pre-setup-report.md`
### Phase 2: 매니페스트 레포지토리 + ArgoCD 산출물
- 매니페스트 레포지토리: {MANIFEST_REPO_URL}
- ArgoCD Application YAML: argocd/*.yaml
- ArgoCD Application 등록: 완료
- ArgoCD 준비 보고서: `deploy-argocd-prepare.md`
### Phase 3: CI/CD 파이프라인 산출물
- 백엔드: {파이프라인 파일 경로} (빌드+푸시+manifest tag 업데이트)
- 프론트엔드: {파이프라인 파일 경로} (빌드+푸시+manifest tag 업데이트)
- AI 서비스: {파이프라인 파일 경로} (빌드+푸시+manifest tag 업데이트)
### 다음 단계
1. CI 파이프라인 실행하여 전체 흐름 검증 (빌드 → 푸시 → manifest 업데이트 → ArgoCD 자동 배포)
MUST 규칙
| # | 규칙 |
|---|
| 1 | <!--ASK_USER--> 발견 시 AskUserQuestion 도구를 호출할 것 (텍스트 출력 금지) |
| 2 | CI 도구 선택(Jenkins/GitHub Actions)에 따라 가이드 선택 매트릭스를 참조하여 해당하는 가이드만 참조할 것 (클라우드별 분기 불필요) |
| 3 | CI 파이프라인에 kubectl apply를 포함하지 않을 것. 마지막 단계는 manifest repo image tag 업데이트여야 함 |
| 4 | [실행정보] 블록을 에이전트 프롬프트에 반드시 포함할 것 — CI 도구 + 레지스트리유형 조합에 맞는 템플릿 사용 |
| 5 | GitHub Actions 가이드 내 클라우드별 조건부 섹션이 [실행정보]의 CLOUD 값에 따라 올바르게 적용되도록 할 것 |
| 6 | Phase 0의 사전 도구 체크는 설치 여부 확인만 수행. 미설치 시 Phase 1에서 가이드(cicd-pre-setup.md) 기반 자동 설치 진행. Phase 0에서 직접 설치 금지 |
| 7 | Agent: {agent-name}이 명시된 Step은 메인 에이전트가 직접 수행 금지. 반드시 프롬프트 조립 규칙에 따라 서브에이전트 호출 |
| 8 | 외부 가이드({NPD_PLUGIN_DIR}/resources/guides/cicd/*.md)가 명시된 Step은 해당 가이드를 반드시 Read로 로드한 뒤 절차를 수행할 것. SKILL.md 본문의 요약만 보고 직접 수행하면 스킬 미준수로 간주 |
완료 조건
검증 프로토콜
- 산출물 파일 존재 확인 (매니페스트 레포 구조, ArgoCD YAML, 파이프라인 파일)
- ArgoCD Application YAML 유효성 검사 (
kubectl apply --dry-run=client -f argocd/)
- Kustomize 유효성 검사 (
kubectl kustomize dry-run)
- 파이프라인 파일 문법 검증 (변수 참조
${variable} 사용, \${variable} 사용 금지 등)
- Phase 1 / Step 2 도구 설치 검증:
kubectl get po -n jenkins (Jenkins 선택 시), kubectl get po -n sonarqube, kubectl get po -n argocd
- Phase 1 / Step 1 사전작업 검증:
kubectl get storageclass (AWS), kubectl get nodepool (AWS/Azure)
- Phase 1 / Step 3 Nginx 검증:
ssh {VM_HOST} 'sudo nginx -t'
상태 정리
완료 시 임시 상태 파일 정리. 산출물은 유지.
