Bitbucket Pipelines 살펴보기

콜트·2021년 12월 18일

Bitbucket을 이용해서 CI / CD 를 위한 파이프라인 설정을 위해 살펴보다 각각의 키워드들에 대해 정리해두면 좋을 것 같아 간단한 설명과 함께 정리해둔다(예제는 우선 공식 문서를 참고하도록 하고, 추후에 작성하도록 한다).

Pipeline

Bitbucket에는 pipeline이라는 내장된 CI / CD 서비스가 있다.

기본적으로 bitbucket-pipelines.yml 에 script를 작성하고 이를 저장소에 커밋하면 Bitbucket에서 알아서 이를 인식하고 해당 설정에 따라 CI / CD가 진행된다. 즉, 저장소를 기반으로
CI / CD 를 수행할 수 있다.

Bitbucket에서는 기본적으로 클라우드에서 컨테이너를 생성하며, 작성한 스크립트는 Bitbucket의 자체 Docker Engine에서 실행되기 때문에, 우리가 원하는 환경에서 script를 제대로 실행하려면
image 라는 속성에 대해서 명시해줄 필요가 있다.

ex) image: openjdk:11

추가적으로, pipeline의 각 단계는 별도의 Docker 컨테이너를 실행한다. 따라서 원하는 경우 다른 이미지를 선택하여 각 단계마다 각각 다른 유형의 컨테이너를 사용할 수 있다.

Configure Syntax

아래는 Bitbucket에서 제공해주는 CI / CD pipeline 환경을 이용하기 위해서 작성하는 bitbucket-pipelines.yml 에 작성하는 스크립트 내의 키워드 및 설명이다.

Bitbucket Pipelines - Validator 에서
bitbucket-pipelines.yml 을 직접 작성해보고 적합한 문법인지 확인해볼 수 있다.

Basic configuration

기본 설정 구성은 아래와 같다.

(Basic configuration example)

default
- 분기별 파이프라인이 정의되어 있지 않는 한 저장소에 푸시될 때마다 실행된다.
- 특정 브랜치가 정의되어 있지 않은 경우 실행된다고 보면 된다(branches 속성).
- tags, bookmark 에서는 실행되지 않는다.
branches
- 특정 브랜치에 대한 파이프라인을 정의할 때 사용한다.
- 지정한 브랜치와 같은 이름을 가진 저장소의 브랜치에 적용된다.
tags
- 태그에 대한 파이프라인을 정의할 때 사용한다.
- 지정한 태그와 같은 이름을 가진 저장소의 태그에 적용된다.
bookmarks
- 북마크에 대한 파이프라인을 정의할 때 사용한다.
pull requests
- pull request 에 대해서 실행되는 파이프라인을 정의할 때 사용한다.
- 실행전에 대상 브랜치를 작업 브랜치에 병합하며, 병합에 실패하면 파이프라인이 중단된다.
- 이는 기본 파이프라인과 함께 실행되므로 정의가 겹칠 경우 동시에 여러개의 파이프라인이 실행될 수 있다.
runs-on
- 파이프라인에서 러너 라는 녀석을 사용할 수 있게 할 때 사용한다. 러너 가 뭔지 아직 잘 모르겠다. 실행을 대신 해주는 녀석으로 보이는데, 잘 사용할 일이 없을 것 같다.
custom
- Bitbucket Cloud 인터페이스에서 수동으로 실행하거나 예약하는 것만 가능한 파이프라인을 정의할 때 사용한다.

Advanced configuration

variables
- custom 파이프라인의 경우, 파이프라인이 시작될 때 제공되는 변수를 포함한다.
- 변수를 활성화하려면 파이프라인을 실행할 때 입력하려는 사용자 지정 파이프라인 아래에 변수를 정의하면 된다.
- 정의한 변수는 script 에서 $와 함께 리터럴로 사용할 수 있다.
- name
  - 변수를 추가로 정의하거나 업데이트할 때 사용한다.
default
- variables 하위에 존재할 경우 기본 변수 값을 사용하게 된다.
parallel
- 병렬적으로 step을 동시에 실행하고 싶을 때 사용한다.
- 파이프라인에서 사용하는 총 빌드시간은 변하지 않지만 결과를 더 빨리 볼 수 있다. 병렬, 직렬 관계 없이 파이프라인 정의에 포함할 수 있는 step의 수는 최대 100개이다.
step
- 빌드 실행 단위를 정의할 때 사용한다. 최대 100개까지 존재할 수 있다.
- bitbucket-pipelines.yml 파일에 선언한 순서대로 실행된다.
- 파이프라인의 각 단계는 별도의 Docker Container 를 시작하여 script에 구성된 명령을 실행한다. name step의 이름을 정의할 때 사용한다.
image
- Bitbucket pipelines는 Docker 컨테이너를 이용하여 빌드를 실행한다.
- 그래서 원하는 환경에서 빌드를 수행하기 위해서는 image에 대한 설정이 필요하다.
- 전역 또는 step 수준에서 image를 정의할 수 있다. 브랜치 수준에서는 image를 정의할 수 없다.
trigger
- step을 자동으로 실행할지 수동으로 실행할지 설정할 수 있다.
- 자동 - automatic, 수동 - manual
deployment
- deployment 단계 환경을 정의할 때 사용한다. 이는 프로젝트의 Deployment 대시보드에 사용된다.
- 프로젝트 - Repository Settings - PIPELINES - Deployments 대시보드에 동일한 이름으로 deployment 환경을 정의해둔 다음 사용해야 한다. 그러지 않으면 CI를
  진행할 때 에러가 발생한다.
- 기본적으로 제공되는 유효한 값으로는 test, staging, production 이 있다.
size
- step에 추가 메모리를 설정할 때 사용한다.
- 설정할 수 있는 값은 1x , 2x 가 있다.
- ex) 기본적으로 Bitbucket의 Docker Container의 메모리는 4GB를 사용하는데, 2x로 설정한다면 8GB를 사용하도록 설정된다.
script
- 순서대로 실행되는 명령들을 정의할 때 사용한다. 사실상 핵심이다.
- 명령들은 선언한 순서대로 실행된다.
pipe
- 이미 설정되어 있는 파이프라인을 사용하고 싶을 때 사용한다. 파이프라인을 import 한다고 생각하면 되겠다.
- 대신, 가져온 파이프라인에서 요구하는 일부 설정값들을 지정해서 입력해주어야 한다.
- 커스텀 파이프라인을 만들고 해당 파이프라인을 가져올 수도 있다.
after-script
- step이 성공하거나 실패했을 때 특정 명령이 실행되도록 지정할 때 사용한다.
- 만약 after-script가 실패할 경우, 해당 섹션에서 더 이상 명령이 실행되지 않으며 이미 완료된 step에 대해서는 영향을 미치지 않는다.
artifacts(산출물, 결과물, 변경사항)
- 단적으로는 step의 결과로 생성되는 파일을 의미한다. 즉, 현재 step에서 일련의 명령들을 거친후 생성되는 산출물 (e.g. **.jar)이다.
- 다음 step에서 현재 step의 산출물을 공유하거나 step이 완료된 이후 산출물을 유지하기 위해 내보낼 때(다운로드 한다던지) 사용한다.
- artifacts에 정의되지 않은 것들에 대해서는 다음 step에서 액세스할 수 없다.
- step에서 생성된 artifacts는 다음 모든 step에서 사용할 수 있다.
- 구체적인 사용 패턴에 대해서는 하단의 참고자료에서 Use glob patterns on the Pipelines yaml file 을 참조하도록 한다.
- 결과물은 14일동안 유지되며, 그 이후엔 삭제된다.
- pipeline result view - Artifact 탭에서 다운로드 할 수 있다.
options
- 모든 파이프라인에 적용되는 전역 설정을 지정할 때 사용한다.
max-time
- options 내에 포함되어 전역 설정으로 동작하게 할 수도 있고, step 내에 포함되어 해당 step에 대해서만 동작하게 할 수도 있다.
- 설정이 적용되는 지점에 대해, 해당 지점이 실행할 수 있는 최대 시간(분)을 정의할 수 있다.
- 0보다 크고 120보다 작은 정수를 사용해야 하며, 지정하지 않으면 기본값은 120이다.
clone
- git clone 관련 설정을 지정할 때 사용한다.
  - LFS - Git LFS 지원 여부를 설정할 때 사용한다(Git에만 해당).
- clone에서 LFS 파일 다운로드 가능 여부를 설정할 수 있다. 기본값은 false다.
  - depth - Git clone의 깊이를 의미한다(Git에만 해당).
- 기본값은 50이며, 0보다 큰 정수를 사용해야 한다.
- enabled - false로 설정할 경우 git clone이 비활성화된다. 기본값은 true다.
  - 빌드시 소스 코드에 액세스할 필요가 없으면 비활성화하여 빌드 시간을 절약할 수도 있다.
oidc
- openID Connect 사용 가능 여부를 설정할 때 사용한다.
condition
- 특정 조건을 설정해서, 해당 조건을 충족하는 경우에만 step이 실행되도록 하기위해 사용한다.
- 현재 지원되는 유일한 조건은 changesets 뿐이다(참고자료를 보자).

Conditions and merge checks

definitions
- 전역적으로 적용되는 설정을 정의할 때 사용한다.
- 내부에 services, caches 등을 선언할 수 있다.
services
- 파이프라인은 서비스에 대해 별도의 도커 컨테이너를 가동할 수 있는데, 이때 사용한다.
caches
- 빌드를 수행할 때 각각의 단계(step)에 대해 의존성을 매번 새로 받게 되는데, 이때 캐시를 사용하여 기본적으로 서버에 해당 의존성을 다운로드한 다음 매번 빌드에 로컬로 로드하여 사용할 수 있게 해준다.
  즉,
- 새롭게 의존성을 다운로드하지 않게 되어 빌드 시간을 단축할 수 있다.

YAML anchors

중복되는 작업이 있을 경우, 이를 정의하고 재사용할 수 있게 해준다. 작업을 정의할 때는 & 를 사용하고, 해당 작업을 참조하여 사용할 때는 * 를 사용한다.

image: openjdk:11

build-hello-world: &build-project
  - step:
      script:
        - chmod +x gradlew
        - ./gradlew clean && ./gradlew build

pipelines:
  branches:
    main:
      - <<: *build-project

anchor 문법을 사용하여 정의한 구문을 참조하여 재사용할 때는 <<: *somthing 과 같이 사용해야 한다.
- 참고 : Bitbucket pipeline reuse of code

Global configuration options(전역 구성 옵션)

(Global configuration options example)

Build and test Gradle projects (Java)

Gradle은 Gradle Wrapper라는 것을 제공하는데, 이는 기본적으로 Gradle이 설치되어 있지 않아도 언제나 같은 Gradle 버전을 사용할 수 있도록 해준다. 단, Gradle Wrapper를 저장소에
커밋해야 하며, 이는 Gradle project에서 권장되는 방식이다.

Gradle Wrapper를 사용하면 아래의 2가지가 보장된다.

Gradle 프로젝트의 경우, Gradle을 빌드 환경에 수동으로 따로 설치할 필요가 없다.
프로젝트는 항상 동일한 Gradle 버전으로 빌드된다.

저장소에 커밋하기 전에 래퍼 스크립트를 실행 가능하게 만드는 것이 좋다.

chmod +x gradlew

그 다음, Gradle Wrapper 를 이용해서 Gradle project를 빌드할 수 있다. 아래는 그 예제다.

image: openjdk:11

pipelines:
  default:
    - step:
        script:
          - chmod +x gradlew
          - ./gradlew clean && ./gradlew build

참고자료

콜트

개발 블로그이지만 꼭 개발 이야기만 쓰라는 법은 없으니, 그냥 쓰고 싶은 내용이면 뭐든 쓰려고 합니다. 코드는 깃허브에다 작성할 수도 있으니까요.