GoCD 설치 및 기본 사용법 정리 (Feat. Kubernetes)

 

0. 들어가며

기존에는 Jenkins + ArgoCD 조합으로 CI/CD를 구성하고 있었지만, 중앙 집중형 파이프라인 관리에 대한 대안을 찾던 중 GoCD를 알게 되어 간단히 학습해보고자 한다. 
 
이번 포스팅에서는 GoCD가 어떤 도구인지 간단히 소개하고, Kubernetes 환경에서의 설치 방법과 기본 파이프라인 구성 및 실행 과정까지 단계별로 정리해 본다.
 

1. GoCD 란

https://www.gocd.org/

 
GoCD는 ThoughtWorks에서 만든 오픈소스 CI/CD 파이프라인 도구이다.
특히 지속적 배포(Continuous Delivery)에 초점을 두고 설계된 툴로, 복잡한 배포 흐름을 시각적으로 표현하고 관리하기에 강점이 있다.
 
Jenkins처럼 자유롭게 커스터마이징 가능한 플러그인 시스템은 부족하지만, 대신 파이프라인 간의 의존성과 흐름을 명확하게 표현할 수 있고, 중앙 집중형으로 파이프라인을 관리할 수 있다는 점이 특징이다.
 
✅ 주요 특징
• 파이프라인 시각화: 파이프라인, 스테이지, 잡, 태스크 구조를 명확하게 보여준다.
• 중앙 집중형 파이프라인 설계: 여러 팀이나 서비스가 하나의 중앙 플랫폼을 기준으로 구성 가능.
• 환경별 파라미터, 조건 분기 등 유연한 설정
• Pipelines as Code 지원:. gocd.yaml로: .gocd.yaml로 정의해서 코드로 파이프라인 관리 가능.
 

2. GoCD 설치하기

Helm Chart 설치
GoCD는 Linux, Window, MacOS 등 다양한 설치 환경을 제공하며, 쿠버네티스 환경에서는 HelmChart를 제공한다.
• 차트 버전 : gocd-2.13.2
• GoCD 버전 : 25.1.0

# GoCD Helm 저장소 등록
helm repo add gocd https://gocd.github.io/helm-chart
helm repo update

# GoCD 설치 (gocd 네임스페이스 생성 포함)
helm install gocd gocd/gocd --namespace gocd --create-namespace


# 헬름 차트 폴더 생성
# helm pull gocd/gocd --untar

# 차트 확인 
NAME    NAMESPACE    REVISION    UPDATED                                 STATUS      CHART          APP VERSION
gocd    gocd         1           2025-04-03 10:51:11.709109 +0900 KST    deployed    gocd-2.13.2    25.1.0     


# 리소스 상태 확인
kubectl get pod,svc,pvc -n gocd
NAME                           READY   STATUS    RESTARTS   AGE
gocd-server-5cb4c95658-m8kkq   1/1     Running   0          97m

NAME                  TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
service/gocd-server   NodePort   10.100.84.18   <none>        8153:31151/TCP   97m

NAME                                STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS        AGE
persistentvolumeclaim/gocd-server   Bound    pvc-d183754d-3c89-472a-b5c6-51f96d657a4d   2Gi        RWO            nfs-client-retain   97m

 
리소스 확인

kubectl get pod,svc,pvc
NAME                               READY   STATUS    RESTARTS      AGE
pod/gocd-server-5cb4c95658-ww989   1/1     Running   7 (19h ago)   19h

NAME                  TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
service/gocd-server   NodePort   10.100.84.18   <none>        8153:31151/TCP   26h

NAME                                STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS        AGE
persistentvolumeclaim/gocd-server   Bound    pvc-d183754d-3c89-472a-b5c6-51f96d657a4d   2Gi        RWO            nfs-client-retain   26h

 
기본적으로 NodePort 방식으로 서비스가 노출되어 있으므로, 브라우저에서 아래와 같이 접속 가능하다

http://<NODE_IP>:<NodePort>
ex) http://192.168.0.10:31151

GoCD 초기화면

3. 파이프라인 생성

GoCD에서는 파이프라인 생성 방식을 두 가지로 지원한다
 
1. Use Pipeline Wizard
웹 UI를 통해 손쉽게 파이프라인을 만들 수 있는 방식이다.
클릭 몇 번이면 빠르게 구성할 수 있어서 실습이나 간단한 테스트용으로 유용하다.
 
2. Use Pipelines as Code
파이프라인 정의를 .yaml 형식으로 코드로 관리하는 방식이다.
버전 관리가 가능하고 협업에 적합하기 때문에 운영 환경에서는 보통 이 방식을 선호한다.

"Use Pipeline Wizard" vs "Use Pipelines as Code

 
먼저, UI 기반인 Pipeline Wizard를 통해 파이프라인을 하나 만들어보고 실행해 보자.

Part 1 - Material 설정

파이프라인 생성 첫 단계는 바로 Material 설정이다
Material이란 GoCD에서 파이프라인이 동작하기 위해 필요한 소스 코드의 위치를 의미한다.
즉, 어떤 저장소에서 코드를 가져와 파이프라인을 돌릴지를 지정하는 개념이다.
 
예를 들어 GitHub에 있는 프로젝트 레포지토리를 Material로 등록하면, 해당 저장소에 변경이 생길 때 파이프라인을 자동으로 트리거할 수 있다.

Part 2 - Pipeline Name

파이프라인을 정의하는 항목으로, 이프라인은 워크플로우 단위이며, 하나 이상의 스테이지(Stage)를 포함한다.
 
✅ 템플릿 사용
템플릿을 활성화하면, 이미 정의된 템플릿 파이프라인을 재사용할 수 있다. 협업에서, 휴먼에러를 줄일 수 있어 좋은 기능이다.
✅ 파라미터 사용
파라미터는 환경별로 변경되는 값들이 있다면 변수화하여 파이프라인 안에서 유연하게 사용할 수 있다.

Part 3 - Stage Details

스테이지(Stage)는 파이프라인 내에서 실행 순서를 제어하는 단위로, 하나 이상의 Job을 포함한다.
 
✅ Automatically run this stage on upstream changes
이 옵션을 활성화하면 이전 스테이지 또는 파이프라인에 변경이 생겼을 때 자동으로 이 스테이지가 실행된다.

Part 4 - Job and Tasks

Job은 스테이지 안에서 실행되는 작업 단위다. 보통 빌드, 테스트, 배포 같은 단계로 나눌 때 기준이 된다.
Tasks는 잡 안에서 실행할 세부 명령어를 말한다
 
GoCD는 UI 상에서 프롬프트 창을 제공해 명령어를 쉽게 추가할 수 있도록 도와준다.
 
✅ Variables
• Plain Text Variables: 평문 변수, 그냥 환경변수처럼 사용할 수 있음
• Secure Variables: 민감한 값(API 키 등)은 여기서 입력하면 암호화되어 처리됨
요하다.

 

4. 파이프라인 실행

파이프라인 구성이 모두 끝났다면 저장 후 실행하면 된다.

하지만, 처음 실행할 때, 무한정 에이전트를 찾지 못하고 무한정에서 멈춰 있을 것이다.

 
에이전트를 찾지 못하는 이유? 🤔 
Kubernetes 환경에서 GoCD는 서버에 고정된 Agent가 있는 게 아니라, Elastic Agent라는 개념을 통해 필요할 때마다 에이전트 파드를 동적으로 생성해 작업을 처리한다. 하지만 기본적으로는 이 Elastic Agent 설정이 활성화되어 있지 않아서, GoCD는 에이전트를 계속 찾다가 멈춰 있게 된다.
 
Elastic Agent 설정
Elastic Agent 설정은 아래 메뉴에서 확인할 수 있다:
• Admin > Elastic Agents Configuration
 
Helm 설치 시 기본으로 함께 설치된 demo-app 기반의 Elastic Agent 플러그인이 있다.
이를 파이프라인에 연결하여 사용하도록 하자.

 
UI에서는 개별 파이프라인에 대해 Elastic Agent를 설정하는 화면이 없기 때문에, 직접 XML 설정을 수정해야 한다. 모든 GoCD의 설정을 XML 즉, 코드로 관리하기 때문에, 쉽게 이식 및 설정이 가능하다.

Config XML 메뉴 화면

Config XML에서 에이전트 설정
• Admin > Config XML로 이동
• 생성한 파이프라인에서 <job> 항목에 다음과 같은 agent profile을 명시한다고 저장한다.

 
설정을 저장한 후, 실행 중이던 파이프라인은 Cancel 하고 다시 실행해 보자.

 
 
파이프라인 실행 확인
이번엔 정상적으로 잡이 실행되며, 콘솔 로그가 출력되는 것을 확인할 수 있다. UI 상에서 터미널 아이콘을 클릭하면, 각 Job에 대한 로그도 확인 가능하다.

파이프라인 콘솔 로그 확인

 
잡이 실행되면 에이전트 파드가 동적으로 생성되는 것을 확인할 수 있다.

kubectl get pod -n gocd
NAME                                              READY   STATUS    RESTARTS      AGE
gocd-agent-b343a000-f4e6-4d8b-a76e-d8dddc7c2d9a   1/1     Running   0             26s
gocd-server-5cb4c95658-ww989                      1/1     Running   0             21h

 
등록한 Task가 문제없이 실행되었는지 로그를 통해 확인하자.

파이프라인 빌드 로그 확인

5. Pipeline as a Code

GoCD에서는. yaml 파일을 통해 파이프라인을 정의할 수 있는 기능을 제공한다.
이는 코드 기반으로 파이프라인을 관리할 수 있게 해주며, 운영 환경에서는 Wizard 방식보다 훨씬 유리하다

gocd-yaml-config-plugin

YAML 파이프라인을 사용하려면 gocd-yaml-config-plugin이 필요하다.
다행히 GoCD 17.8.0 이상 버전부터는 기본으로 포함되어 있으며, Helm chart로 설치한 경우에도 자동 설치되어 있다.
• GoCD 버전: 25.1.0
• 확인 위치: Admin > Plugins

 
기본적으로 파이프라인으로 인식하는 yaml 파일의 이름은 .gocd.yaml이지만, 설정을 통해 다른 이름이나 패턴도 지정 가능하다.

GoCD yaml 파일 경로 설정

파이프라인 생성

그룹 생성 
GoCD에서는 파이프라인을 논리적으로 묶어서 관리할 수 있도록 그룹(Group)이라는 개념을 제공한다.
하나의 그룹 안에는 여러 개의 파이프라인을 배치할 수 있고, 그룹 단위로 권한 설정도 가능하다.
 
ex) 팀별로 backend, frontend, infra 등의 그룹을 만들어 파이프라인을 나누면 협업과 운영이 훨씬 수월해진다.
 
이번 실습에서는 sample-group이라는 그룹을 생성해 보자.

샘플 그룹 생성

 

샘플 그룹 확인

샘플 파이프라인 작성(.gocd.yaml)
UI Wizard 방식으로 만들었던 파이프라인을 YAML로 구성한 예시

# .gocd.yaml
pipelines:
  sample-pipeline:
    group: sample-group
    materials:
      git-repo:
        git: https://github.com/hackjap/cicd.git
    stages:
      - build:
          jobs:
            build-job:
              tasks:
                - exec:
                    command: echo
                    arguments: ["Hello from GoCD YAML Pipeline!"]

 
파이프라인 불러오기: Config Repositories
YAML 파일을 GoCD에서 인식하려면 반드시 Config Repository 등록이 필요하다.
• .gocd.yaml 파일이 있는 저장소를 Config Repo로 등록하면,
• 해당 파일이 수정될 때마다 자동으로 파이프라인이 생성되거나 갱신된다.
 
Materials vs Config Repositories
GoCD에서는 위에서 생성한, Materials와 Config Repositories라는 비슷한 구조를 사용하므로 있지만, 아래와 같이 목적이 다르므로 명확히 구분할 필요가 있다.

항목	설명	예시
Materials	파이프라인이 실행될 트리거 대상 소스코드 저장소	앱 코드, 빌드 대상 코드 등
Config Repositories	.gocd.yaml, templates.yaml 등 GoCD 설정 파일이 있는 저장소	파이프라인 정의, 템플릿 관리 등

 

materials vs config repository

 
sample-group에서의 파이프라인을 생성할 때, Config Repository에 대한 접근 권한이 기본적으로 설정되어 않기 때문에, 아래와 같은 에러가 발생한다.

 
XML 파일 수정: Config Repository에 대한 접근 권한을 허용해 준다.( Ignore Security)

config repositiory 보안 옵션 헤제

 
이제 성공적으로 Config Repository가 등록됨을 확인할 수 있습니다.

Config Repository 생성 확인

 
파이프라인 생성 확인 
Config Repository가 정상적으로 등록이 되면, 자동으로 생성된 파이프라인 확인할 수 있다.

.gocd.yaml로 설정한 파이프라인 생성 확인

 
이제 다시 파이프라인을 실행해 보면, 정상적으로 동작함을 확인할 수 있다.

gocd.yaml로 설정한 파이프라인 실행 및 확인

 
 
다음 포스팅에서는 GoCD 파이프라인의 다양한 기능들과 YAML을 활용한 선언적 파이프라인 관리 방법에 대해 더 깊이 알아보자.
 

Reference

• https://docs.gocd.org/current/ - GoCD 공식 문서
• https://toss.tech/article/slash23-devops?ref=codenary - 토스 도입 사례
• https://velog.io/@dipokalhhj/GoCD-Pipeline-구축 - KrBlog GoCD 구축하기
• https://www.codenary.co.kr/techstack/detail/gocd - 국내 GoCD 사용 사례