Buildkite에서 자동화된 API 테스트를 실행하려면 `.buildkite/pipeline.yml` 파일에 Apidog CLI를 설치하고, 환경에 대해 `apidog run`을 실행하며, HTML 보고서를 빌드 아티팩트로 업로드하는 명령 단계를 정의합니다. 이 가이드는 Buildkite가 시크릿(secrets)을 처리하여 Apidog 액세스 토큰이 로그에 유출되지 않도록 하는 방법을 포함한 전체 파이프라인을 안내합니다. Apidog 테스트가 이미 존재한다고 가정합니다. 시각적으로 한 번 빌드한 다음 CI에서 하나의 명령으로 실행합니다.
시작하기 전에 한 가지를 명확히 하겠습니다. Buildkite는 CI/CD 플랫폼입니다. 이는 Docker 내부의 이미지 빌드 백엔드인 Docker BuildKit과는 다릅니다. 이름이 비슷해 보이지만, 서로 관련 없는 제품입니다. 이 문서는 전적으로 CI/CD 플랫폼인 Buildkite에 관한 것입니다.
Buildkite란 무엇인가요
Buildkite는 하이브리드 모델을 기반으로 구축된 CI/CD 플랫폼입니다. 브라우저에서 볼 수 있는 대시보드와 빌드 오케스트레이션을 제공하는 호스팅된 제어 플레인과 실제로 작업을 실행하는 에이전트로 구성됩니다.
이러한 분리는 중요합니다. 제어 플레인은 작업을 스케줄링하지만, 실제 작업은 에이전트에서 실행됩니다. 자체 인프라나 클라우드에 에이전트를 자체 호스팅하거나, Buildkite가 관리하는 컴퓨팅인 Buildkite 호스팅 에이전트를 사용할 수 있습니다.
이것이 Buildkite를 완전히 호스팅되는 CI 시스템과 차별화하는 주요 특징입니다. Buildkite가 빌드를 조정하는 동안 코드와 시크릿은 자체 머신에 유지될 수 있습니다. API 테스트의 경우, 이는 테스트가 서비스와 네트워크 액세스가 이미 존재하는 곳에서 실행됨을 의미합니다.
Buildkite 에이전트 자체는 오픈 소스입니다. Go로 작성되었으며 MIT 라이선스에 따라 GitHub에서 소스 코드를 제공합니다. 에이전트를 둘러싼 플랫폼과 제어 플레인은 상용 SaaS 제품입니다.
Buildkite는 무엇에 사용되나요
팀은 코드 변경으로 트리거되는 모든 종류의 자동화된 작업(아티팩트 빌드, 유닛 및 통합 테스트 실행, 서비스 배포, 엔드투엔드 검사 실행)을 Buildkite를 사용하여 실행합니다. 에이전트가 자체 하드웨어에서 실행될 수 있으므로 컴퓨팅, 네트워크 경계 또는 GPU와 같은 하드웨어에 대한 제어가 필요한 팀에서 흔히 사용됩니다.
API 테스트는 이 모델에 잘 맞습니다. 테스트가 스테이징 또는 테스트 환경에 도달하고, 실제 응답을 확인하며, 계약이 깨질 때 배포를 차단하기를 원할 것입니다. Buildkite는 아래에서 사용할 바로 그 흐름을 모델링하는 단계 유형을 제공합니다.
다른 옵션과 Buildkite를 비교하고 있다면, API 팀을 위한 최고의 지속적 통합 도구에 대한 저희의 요약 기사가 이 사용 사례에 대해 여러 플랫폼이 어떻게 비교되는지 다룹니다.
Buildkite 파이프라인은 어떻게 정의되나요
Buildkite 파이프라인은 단계(steps) 목록입니다. 이들을 정의하는 기본 위치는 리포지토리의 `.buildkite/pipeline.yml` 파일입니다. 빌드가 시작되면 Buildkite는 `pipeline.yml`이라는 파일을 포함하는 `.buildkite`라는 디렉토리를 찾습니다. 리포지토리 루트에 숨김 파일이 아닌 `buildkite/` 디렉토리가 있어도 작동합니다.
최상위 키는 `steps:`이며, 목록을 포함합니다. API 테스트에 가장 많이 사용할 단계 유형은 다음과 같습니다.
- 명령 단계(Command steps)는 에이전트에서 셸 명령을 실행합니다. 이곳에서 테스트가 실행됩니다.
- 대기 단계(Wait steps)는 이전의 모든 단계가 완료될 때까지 파이프라인을 일시 중지합니다. 이는 ` - wait` 목록 항목으로 작성합니다.
- 블록 단계(Block steps)는 ` - block: "Label"`로 작성되며, 수동 승인 게이트를 생성합니다. 사람이 클릭하여 계속 진행하며, 이는 프로덕션 배포 전에 유용합니다.
명령 단계는 자주 사용하게 될 키들을 지원합니다: 이름 지정 및 참조를 위한 `label`과 `key`, 스크립트를 위한 `command` 또는 `commands`, 환경 변수를 위한 `env`, 타겟팅을 위한 `agents`, 시크릿 값 주입을 위한 `secrets`, 보관할 파일을 위한 `artifact_paths`, 팬아웃을 위한 `parallelism`, 그리고 값 집합에 걸쳐 동일한 단계를 실행하기 위한 `matrix`입니다.
`agents` 키는 태그 쌍의 해시입니다. 이를 사용하여 단계를 올바른 에이전트로 라우팅합니다. 예를 들어 `queue: "tests"`와 같습니다. 태그를 사용하면 올바른 네트워크 액세스 또는 도구를 가진 에이전트에서 테스트 작업을 유지할 수 있습니다.
API 테스트를 실행하는 복사-붙여넣기 파이프라인
여기 Apidog CLI를 설치하고, 환경에 대해 테스트 시나리오를 실행하며, HTML 보고서를 업로드하는 최소한의 `.buildkite/pipeline.yml`이 있습니다. Apidog CLI는 명령줄에서 Apidog 테스트 시나리오를 실행하는 Node.js 도구입니다.
steps:
- label: ":test_tube: API tests (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
플래그에 대한 몇 가지 참고 사항입니다. `-t`는 실행하려는 테스트 시나리오 또는 시나리오 디렉토리의 ID입니다. `-e`는 런타임 환경 ID로, 테스트에서 사용하는 기본 URL과 변수를 선택합니다. `-r html,cli`는 사람이 읽을 수 있는 터미널 요약과 HTML 보고서 파일을 모두 요청합니다. `--access-token`은 Apidog 토큰을 전달하여 CLI가 프로젝트에 접근할 수 있도록 합니다.
Buildkite 에이전트 호스트는 이미 `buildkite-agent` 바이너리를 사용할 수 있습니다. 이는 작업을 실행하는 주체이기 때문입니다. `apidog-cli`만 직접 설치하면 됩니다. 각 플래그에 대한 자세한 내용은 Apidog CLI 완전 가이드를 참조하십시오.
터미널에서 단일 API를 먼저 실행하는 단계별 지침을 원한다면, Apidog CLI 명령줄 테스트 튜토리얼이 CI에 연결하기 전에 좋은 준비가 될 것입니다.
Buildkite 시크릿을 사용하여 Apidog 액세스 토큰 전달하기
Apidog 액세스 토큰은 자격 증명입니다. 이 토큰은 `pipeline.yml`에 저장되거나 빌드 로그에 인쇄되어서는 안 됩니다. Buildkite는 이를 위한 고유한 기능인 Buildkite 시크릿(secrets)을 제공합니다.
Buildkite 시크릿은 암호화된 키-값 저장소입니다. 값은 저장 시 및 TLS를 통한 전송 중에 암호화되며, Buildkite 서버에서 복호화되고, 클러스터별로 범위가 지정되며 각 클러스터는 자체 암호화 키를 가집니다. Buildkite 호스팅 에이전트와 자체 호스팅 에이전트 모두에서 작동합니다. 로그에 나타나는 모든 시크릿 값은 자동으로 수정(redact)됩니다.
저장된 시크릿을 사용하는 방법은 두 가지가 있습니다. 첫 번째는 명령 단계의 `secrets:` 키입니다. 가장 간단한 목록 형태에서는 환경 변수 이름이 시크릿 키와 일치합니다.
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
저장된 시크릿이 원하는 환경 변수와 다른 이름을 가지고 있다면, 해시 형태를 사용하십시오. 키는 환경 변수 이름이고 값은 시크릿의 키입니다.
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # env var name : Buildkite secret key
두 번째 방법은 에이전트 CLI를 사용하여 스크립트 내에서 시크릿을 명령적으로 가져오는 것입니다. 이는 값을 언제 읽을지 정확히 제어하고 싶을 때 유용합니다.
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Buildkite 시크릿이 유일한 옵션은 아닙니다. 자체 호스팅 에이전트에서는 각 작업 시작 시 실행되어 값을 환경으로 내보내는 스크립트인 `environment` 에이전트 훅을 사용할 수 있습니다. `$BUILDKITE_PIPELINE_SLUG` 또는 `$BUILDKITE_STEP_KEY`와 같은 변수를 사용하여 올바른 작업에만 시크릿이 로드되도록 할 수 있습니다. 또한 Buildkite 플러그인을 통해 AWS Secrets Manager, HashiCorp Vault 또는 GCP와 같은 외부 저장소에서 가져올 수도 있으며, 이 경우 시크릿은 Buildkite에 저장되거나 전송되지 않습니다.
일반 `env:` 값은 민감하지 않은 구성에 적합하지만, 토큰은 거기에 두지 마십시오. 토큰이 시크릿 저장소에서 CLI로 어떻게 흐르는지에 대한 자세한 내용은 Apidog CLI 인증 가이드를 참조하십시오.
HTML 보고서를 아티팩트로 업로드하기
`-r html` 리포터는 HTML 보고서를 에이전트 작업 공간의 로컬 경로에 작성합니다. 이 파일은 저장하지 않으면 작업이 끝날 때 사라집니다. `buildkite-agent artifact upload` 명령은 이 파일을 보존합니다.
buildkite-agent artifact upload "apidog-reports/**/*"
글로브 패턴 주위의 따옴표는 중요합니다. 이는 셸이 에이전트가 패턴을 보기 전에 패턴을 확장하는 것을 방지하여 에이전트가 직접 일치 작업을 수행하도록 합니다. 업로드된 아티팩트는 기본적으로 Buildkite 관리형 저장소로 이동하며, 6개월 보존 기간과 아티팩트당 5GB 제한이 있습니다. 다른 곳으로 보내고 싶다면 두 번째 인수로 대상을 전달할 수 있습니다.
빌드가 실행된 후, 보고서는 빌드의 아티팩트 탭 아래에 나타납니다. 빌드를 검토하는 누구든지 이를 다운로드하여 어떤 어설션이 통과하거나 실패했는지 확인할 수 있습니다. 보고서 형식을 먼저 이해하고 싶다면, Apidog CLI 테스트 보고서 가이드가 CLI, HTML 및 JSON 출력에 대해 설명합니다.
여러 환경에서 병렬로 테스트 실행하기
동일한 스위트를 여러 환경에서 동시에 실행하고 싶을 때 `matrix`를 사용하십시오. Buildkite는 하나의 단계 정의를 매트릭스 값당 하나의 작업으로 확장하며, 이들은 병렬로 실행됩니다.
steps:
- label: ":test_tube: API tests {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # staging environment id
- "358172" # production environment id
여기에서 `{{matrix.env}}`는 레이블과 `-e` 플래그 모두에 대체되어 각 작업이 다른 Apidog 환경을 대상으로 합니다. 단일 작업의 동일한 복사본을 팬아웃(fan out)하고 싶다면, 매트릭스 대신 단계에 `parallelism: 5`를 설정하십시오.
하나의 시나리오가 CSV 또는 JSON 파일의 행을 반복하는 데이터 중심 실행의 경우, Apidog CLI는 Buildkite 매트릭스 대신 자체 `-d` 플래그로 이를 처리합니다. Apidog CLI 데이터 중심 테스트 가이드는 데이터 파일을 시나리오에 공급하는 방법을 보여줍니다.
테스트 뒤에 배포 게이트 설정하기
일반적인 형태는 다음과 같습니다: 테스트 실행, 완료될 때까지 대기, 사람에게 승인 요청, 그리고 배포. Buildkite는 `wait` 및 `block` 단계로 이를 모델링합니다.
steps:
- label: ":test_tube: API tests"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: Deploy?"
branches: "main"
- label: ":rocket: Deploy"
command: "scripts/deploy.sh"
`wait` 단계는 테스트가 완료될 때까지 파이프라인을 유지합니다. `block` 단계는 수동 클릭을 위해 일시 중지되며 `branches:`를 통해 `main` 브랜치로 제한됩니다. 누군가 승인한 후에야 배포 단계가 실행됩니다. 이는 실패한 테스트 스위트가 프로덕션에 도달하는 것을 방지합니다. 이에 대한 더 넓은 패턴은 API 테스트를 위한 CI/CD 모범 사례를 참조하십시오.
요약 주석 추가하기
빌드 로그는 길 수 있습니다. 주석은 빌드 페이지 상단에 짧고 형식화된 요약을 추가합니다. 마크다운을 `buildkite-agent annotate`로 파이프하여 생성합니다.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### API test results
All Apidog scenarios passed. [Download the full HTML report](artifact://apidog-reports/index.html)
EOF
`--style` 플래그는 `info`, `warning`, `error`, `success` 값으로 색상과 아이콘을 제어합니다. `--context` 플래그는 주석에 고유 ID를 부여하여, 동일한 컨텍스트를 가진 후속 단계가 새 주석을 추가하는 대신 동일한 주석을 업데이트하도록 합니다. `artifact://` 링크는 검토자가 업로드된 HTML 보고서로 바로 이동할 수 있도록 합니다.
Apidog의 역할
위의 파이프라인은 의도적으로 짧습니다. 테스트를 작성하고 유지 관리하는 고된 작업은 YAML이 아니라 Apidog에서 이루어집니다.
Apidog는 API 설계, 디버깅, 테스트, 모킹 및 문서화를 위한 올인원 API 플랫폼입니다. 시각적 편집기에서 테스트 시나리오를 구축할 수 있습니다. 스크립트 작성 없이 요청을 연결하고, 단계 간에 데이터를 전달하며, 어설션을 추가할 수 있습니다. 시나리오가 Apidog 프로젝트에 저장되므로, 팀은 한 곳에서 이를 편집하고 브랜치 지원으로 버전 관리를 할 수 있습니다.
CLI는 CI로의 다리입니다. 시나리오를 한 번 빌드하고, 시나리오 및 환경 ID를 가져오면 전체 CI 통합은 단일 apidog run 명령으로 이루어집니다. Apidog에서 테스트를 업데이트하면 다음 Buildkite 빌드는 YAML 편집 없이 변경 사항을 적용합니다. 이러한 단일 명령 특성 덕분에 Apidog는 Buildkite, GitHub Actions 또는 다른 시스템에 깔끔하게 통합될 수 있습니다. 동일한 명령을 다른 플랫폼에서 사용하는 방법에 대해서는 Apidog CLI CI/CD 파이프라인 가이드 및 GitHub Actions와 Apidog CLI 설명서를 참조하십시오.
CI에 어떤 것도 연결하기 전에 먼저 본인의 머신에서 시도해 보려면, 토큰을 사용하여 로컬에서 동일한 명령을 실행하십시오.
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Apidog를 무료로 다운로드하고, 테스트 시나리오를 구축한 다음, 한 줄짜리 `apidog run` 명령을 Buildkite 파이프라인에 추가하십시오.
자주 묻는 질문
Buildkite는 무엇인가요?
Buildkite는 하이브리드 설계를 가진 CI/CD 플랫폼입니다. 호스팅된 제어 플레인이 대시보드를 실행하고 빌드를 오케스트레이션하며, 에이전트가 실제 작업을 실행합니다. 에이전트는 자체 인프라 또는 Buildkite 호스팅 컴퓨팅에서 실행될 수 있습니다. 이름이 비슷하지만 별개의 이미지 빌드 도구인 Docker BuildKit과는 관련이 없습니다.
Buildkite는 무엇에 사용되나요?
팀은 Buildkite를 사용하여 코드 변경으로 트리거되는 작업(아티팩트 빌드, 테스트 실행, 배포)을 자동화합니다. 팀이 자체 하드웨어 또는 자체 네트워크 내에서 빌드를 실행하기를 원하는 경우에 흔히 사용됩니다. API 팀의 경우, 스테이징 및 프로덕션 환경에 대해 자동화된 테스트를 실행하며 테스트 실패 시 배포를 차단할 수 있습니다.
Buildkite는 오픈 소스인가요?
Buildkite 에이전트는 오픈 소스입니다. Go로 작성되었으며 MIT 라이선스에 따라 GitHub에서 소스 코드를 제공합니다. 에이전트를 둘러싼 플랫폼과 제어 플레인은 상용 SaaS 제품이므로, 에이전트 자체만 오픈 소스입니다.
Buildkite는 무료인가요?
네, Buildkite는 Personal이라는 무료 플랜을 제공합니다. 신용 카드 없이 $0이며 만료 기한이 없습니다. 이 플랜에는 3개의 동시 작업, 1명의 사용자, 90일 데이터 보존, 월 500분의 Linux 호스팅 에이전트 사용 시간, 그리고 월 50,000건의 테스트 실행이 포함됩니다. 유료 기능을 평가하기 위한 30일 All Access 체험판도 있습니다.
Buildkite에서 아티팩트를 어떻게 업로드하나요?
명령 단계 내에서 buildkite-agent artifact upload "<pattern>"을 실행합니다. 셸이 아닌 에이전트가 글로브 패턴을 일치시키도록 패턴을 따옴표로 묶으십시오. 파일은 기본적으로 Buildkite 관리형 저장소로 이동하며, 6개월 보존 기간과 아티팩트당 5GB 제한이 있습니다. API 테스트의 경우, 검토자가 빌드의 아티팩트 탭에서 열 수 있도록 HTML 보고서를 업로드합니다.
Buildkite 파이프라인에서 API 테스트를 어떻게 실행하나요?
.buildkite/pipeline.yml에 npm install -g apidog-cli로 Apidog CLI를 설치하는 명령 단계를 추가한 다음, 테스트 시나리오 ID, -e를 통한 환경 ID, 그리고 보고서를 위한 -r html,cli를 사용하여 apidog run을 실행합니다. 액세스 토큰은 Buildkite 시크릿을 통해 전달하고, 빌드 후에 결과가 유지되도록 buildkite-agent artifact upload로 HTML 보고서를 업로드합니다.