GitHub Actions에서 Apidog CLI API 테스트 전체 워크플로우 실행 가이드

GitHub Actions에서 Apidog API 테스트 시나리오를 실행하세요. 전체 워크플로: apidog-cli 설치, 접근 토큰을 비밀로 저장, 병합 제한, 보고서 발행.

Ashley Innocent

Ashley Innocent

15 June 2026

GitHub Actions에서 Apidog CLI API 테스트 전체 워크플로우 실행 가이드

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

API 테스트는 사용자 머신에서는 통과합니다. 하지만 팀원이 로그인 엔드포인트를 깨뜨리는 변경 사항을 병합하고, 고객이 티켓을 제출할 때까지 아무도 알아차리지 못하는 상황이 발생할 수 있습니다. 테스트는 존재했지만, 중요할 때 실행되지 않았습니다. 즉, 병합 전에 풀 리퀘스트에서 실행되지 않은 것입니다.

지속적 통합(CI)은 이러한 간극을 메웁니다. 로컬 터미널에서 테스트를 옮겨와 모든 푸시에 대해, 모든 변경 사항에 대해 자동으로 실행되는 파이프라인으로 이동시킵니다. 특히 API 테스트의 경우, 이를 수행하는 가장 깔끔한 방법은 이미 구축한 시나리오를 정확히 실행하고, 성공/실패 종료 코드를 반환하며, CI가 빌드가 성공(녹색)할지 실패(빨간색)할지 결정하게 하는 명령줄 러너를 사용하는 것입니다.

버튼

요약

CI에서 API 테스트를 실행해야 하는 이유

기억할 때만 실행되는 테스트는 신뢰할 수 없습니다. 시나리오를 작성하는 동안에는 로컬 실행이 좋지만, 팀이 참여하는 순간 문제가 발생합니다. 모든 개발자 머신이 약간씩 다르고, 아무도 모든 푸시 전에 전체 스위트를 실행하지 않기 때문입니다.

CI는 실행을 자동화하고 일관되게 만들어 신뢰 문제를 해결합니다. 모든 풀 리퀘스트는 동일한 깨끗한 러너에서 동일한 환경에 대해 동일한 작업을 트리거합니다. 엔드포인트가 500 오류를 반환하거나 응답 스키마가 변경되기 시작하면, 해당 변경을 일으킨 PR에서 검사가 실패하고 푸시한 사람의 이름이 첨부됩니다. 피드백은 변경 사항이 아직 생생할 때, 즉 프로덕션에서 며칠 뒤가 아니라 몇 분 내에 도착합니다.

API 테스트는 빠르고 결정적이기 때문에 CI에 아주 적합합니다. 시나리오는 실제 엔드포인트를 호출하고, 상태 코드와 응답 본문을 어설션하며, 성공 또는 실패합니다. 불안정한 브라우저나 기다려야 할 렌더링이 없습니다. 이는 API 테스트를 병합 게이트로 이상적으로 만듭니다. 모든 PR에서 실행될 만큼 빠르고, 잘못된 PR을 차단할 만큼 단호합니다. CI/CD가 무엇이며 각 부분이 어떻게 작동하는지에 대한 더 넓은 배경 지식을 원한다면, CI/CD가 무엇이며 어떻게 작동하는지에 대한 기본 가이드를 참조하십시오.

Apidog CLI가 실제로 하는 일

가장 많은 시간을 절약해주는 부분은 CLI용 테스트 코드를 작성하지 않는다는 점입니다.

요청, 어설션, 환경 변수 및 필요한 데이터를 사용하여 Apidog 앱에서 테스트 시나리오를 시각적으로 구축합니다. CLI는 러너입니다. 시나리오 ID와 액세스 토큰이 주어지면, Apidog 프로젝트에서 해당 시나리오를 가져와 앱이 평가하는 방식과 동일하게 요청별로 모든 어설션을 실행하고 평가합니다. 결과는 보고서와 종료 코드입니다.

이러한 설계는 CI에 중요합니다. 대부분의 테스트 러너는 테스트의 별도 코드 표현을 유지하도록 요구하여, 파이프라인에서 실행하는 것과 사용자가 설계한 것이 달라지는 경우가 많습니다. Apidog를 사용하면 팀이 앱에서 이미 유지 관리하는 동일한 시나리오를 파이프라인이 실행합니다. 시각적 편집기에서 어설션을 업데이트하면 다음 CI 실행에 바로 반영됩니다. 동기화를 유지해야 할 두 번째 사본이 없습니다.

바이너리는 apidog이며, npm 패키지 apidog-cli로 배포됩니다. 모든 명령은 apidog run으로 시작합니다. 러너가 더 완전한 자동화 워크플로에 통합되는 모습을 보고 싶다면, Apidog CLI를 Claude Skills와 통합하여 API 테스트를 자동화하는 가이드에서 해당 측면을 다루고 있습니다. 이 글에서는 GitHub Actions 파이프라인에 필요한 플래그에 중점을 둡니다.

시작하기 전에: 필요한 세 가지

워크플로를 실행하려면 세 가지 정보가 필요합니다. 두 가지는 Apidog 프로젝트의 ID이고, 하나는 토큰입니다.

  1. 테스트 시나리오. 아직 만들지 않았다면 Apidog 앱에서 구축하십시오. CLI가 실행할 대상입니다. 로그인 및 프로필 가져오기 시나리오 하나로 시작하기에 충분하며, 나중에 확장할 수 있습니다.
  2. 시나리오 ID 및 환경 ID. 시나리오 ID는 CLI에게 무엇을 실행할지 알려주고, 환경 ID는 어디에서(개발, 스테이징, 프로덕션) 실행할지 알려줍니다. 둘 다 앱에서 확인할 수 있습니다.
  3. 액세스 토큰. 이는 CLI가 Apidog 계정에 인증하여 시나리오를 가져오고 실행할 수 있도록 합니다.

이 모든 것을 한 번에 얻는 가장 깔끔한 방법은 시나리오의 CI/CD 탭을 이용하는 것입니다. 자동화하려는 테스트 시나리오를 열고, CI/CD 탭으로 전환한 다음, 명령줄 옵션을 선택하세요. 액세스 토큰을 추가하고 생성하려면 클릭합니다. Apidog는 액세스 토큰, 시나리오 ID(-t), 환경 ID(-e)가 미리 채워진 전체 apidog run 명령을 자동으로 구성해줍니다. 이 명령을 복사하십시오. 이것이 CI 단계의 기본이 됩니다.

미리 강조할 가치가 있는 한 가지 규칙: 액세스 토큰을 비밀번호처럼 다루세요. 커밋된 워크플로 파일에 붙여넣지 마세요. GitHub Actions 비밀(secret)로 저장하고 환경 변수로 참조하세요. 모든 아래 예시에서는 바로 그 이유 때문에 $APIDOG_ACCESS_TOKEN을 사용합니다.

단계 1: 액세스 토큰을 GitHub 비밀로 저장

GitHub에서 저장소를 엽니다. Settings(설정)로 이동한 다음, Secrets and variables(비밀 및 변수), Actions(액션)로 이동하여 New repository secret(새 저장소 비밀)을 클릭합니다.

저장합니다. 이제 토큰은 미사용 상태에서 암호화되며, 워크플로 실행에만 노출되고 로그에는 절대 인쇄되지 않습니다. 워크플로에서는 ${{ secrets.APIDOG_ACCESS_TOKEN }}으로 참조하고 env: 블록을 통해 CLI에 전달합니다. 시나리오 ID와 환경 ID는 비밀이 아닙니다. 해롭지 않은 ID이므로 워크플로 파일에 직접 작성할 수 있습니다. 토큰만 보호해야 합니다.

팀이 여러 저장소에서 동일한 Apidog 프로젝트를 사용하는 경우, 조직 수준에서 한 번만 비밀을 정의하고 관련 저장소에 접근 권한을 부여하세요. 이름은 같고, 한 곳에서만 갱신할 수 있습니다.

단계 2: 최소 워크플로

저장소에 .github/workflows/api-tests.yml 파일을 생성합니다. 이는 유용한 작업을 수행하는 가장 작은 워크플로입니다. main을 대상으로 하는 모든 풀 리퀘스트에서 시나리오를 실행합니다.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

605067을 사용자 시나리오 ID로, 1629989를 사용자 환경 ID로 교체하십시오. 이 파일을 커밋하고, 풀 리퀘스트를 열고, Checks(검사) 탭을 확인하세요. 작업은 Ubuntu 러너를 시작하고, Node 20을 설치하고, CLI를 설치한 다음, 시나리오를 실행합니다. 모든 어설션이 통과하면 검사가 녹색으로 바뀝니다. 하나라도 실패하면 apidog run은 0이 아닌 값으로 종료되고, GitHub는 검사를 실패로 처리하며, PR에 빨간색 X가 표시됩니다.

그 빨간색 X가 핵심입니다. 무언가 문제가 생겼다는 것을 알기 위해 아무도 로그를 읽을 필요가 없습니다. 실패한 검사는 풀 리퀘스트에 바로 표시됩니다.

설치 단계에 대한 참고: 전역 npm install -g apidog-cli는 간단하고 작동합니다. 러너의 전역 패키지를 변경하고 싶지 않다면, 설치 단계를 건너뛰고 npx를 통해 CLI를 호출할 수 있습니다.

      - name: Run API test scenario
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

두 접근 방식 모두 동일한 시나리오를 실행합니다. npx는 일시적인 러너에서 더 깔끔하고, 전역 설치는 실행 간에 node_modules를 캐시할 때 약간 더 빠릅니다. 팀 스타일에 맞는 것을 선택하세요.

단계 3: 실제로 읽을 수 있는 보고서 발행

녹색 또는 빨간색 체크는 결과를 알려줍니다. 테스트가 실패하면 왜 실패했는지 알고 싶을 것이고, 이를 위해 보고서가 필요합니다.

-r (또는 --reporters) 플래그는 보고서 형식을 제어합니다. 쉼표로 구분된 cli, html, json, junit을 허용합니다. CI의 경우, 두 가지 형식이 중요합니다.

빌드 로그 자체에서 읽을 수 있는 출력을 원한다면 cli도 계속 켜두세요. 다음은 두 보고서 형식을 모두 생성하여 디렉토리에 쓰고, 보고서가 실행 후에도 유지되도록 업로드 단계를 추가하여 업그레이드된 실행 단계입니다.

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

두 가지 세부 사항이 원하는 방식으로 작동하게 합니다. --out-dir 플래그는 CLI에게 보고서를 어디에 작성할지 알려줍니다. 여기서는 ./apidog-reports이며, 업로드 단계에서 이를 가져옵니다. 그리고 업로드 단계의 if: always()가 중요한 부분입니다. 기본적으로 GitHub는 한 단계가 실패하면 이후 단계를 건너뛰지만, 테스트가 실패했을 때 보고서가 가장 필요합니다. if: always()는 테스트 결과에 관계없이 업로드가 실행되도록 강제합니다. 작업이 완료되면 보고서는 실행 요약 페이지의 Artifacts(아티팩트) 아래에 나타나 다운로드할 준비가 됩니다.

-n 1 플래그는 반복 횟수를 한 번 실행으로 설정합니다. 시나리오를 여러 번 연속으로 실행하려면 이 값을 늘리십시오.

GitHub가 다운로드 가능한 파일 대신 주석이 달린 검사로 JUnit 결과를 인라인으로 표시하기를 원한다면, 실행 단계 뒤에 published-test-results 액션을 추가하고 ./apidog-reports/*.xml을 가리키도록 설정하십시오. 이렇게 하면 XML이 실행에 첨부된 성공/실패 요약으로 바뀌어, 로그를 스크롤하는 것이 실용적이지 않은 대규모 스위트에서 유용합니다.

단계 4: 적시에 올바른 환경 테스트

풀 리퀘스트는 스테이징 환경에 대해 테스트해야 합니다. 프로덕션 배포는 프로덕션 환경에 대해 검증되어야 합니다. 동일한 시나리오로 둘 다 수행할 수 있습니다. -e로 환경 ID만 변경하면 됩니다.

일반적이고 견고한 설정은 하나의 워크플로 파일에서 두 가지 트리거를 사용합니다. 풀 리퀘스트는 병합 게이트로 스테이징 환경에 대해 시나리오를 실행합니다. main으로의 푸시(병합 시 발생)는 배포 후 스모크 테스트로 프로덕션 환경에 대해 동일한 시나리오를 실행합니다.

name: API tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Test staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

두 환경 ID(스테이징용 1629989, 프로덕션용 1730055)가 유일한 의미 있는 차이입니다. PR 작업은 검토자가 실패를 검사할 수 있도록 JUnit 보고서를 생성하고 아카이브합니다. 프로덕션 스모크 테스트는 --on-error end를 사용하여 간결하게 실행되고 빠르게 실패하는데, 이는 첫 번째 깨진 어설션에서 중지하여 배포가 잘못되었음을 신속하게 파악할 수 있게 합니다.

--on-error는 알아둘 가치가 있습니다. 시나리오 중간에 단계가 실패했을 때 어떤 일이 일어날지 제어합니다. end는 첫 번째 실패 시 실행을 중지하고 (빠른 피드백, 스모크 테스트에 적합), continue는 모든 나머지 단계를 실행하여 모든 실패를 하나의 보고서에서 볼 수 있게 합니다 (철저한 PR 검사에 적합). ignore는 알려진 불안정한 단계를 실행을 방해하지 않고 건너뜁니다. 어떤 것을 선택하든, 무언가 실패하면 실행은 여전히 0이 아닌 값으로 종료되므로 게이트는 어떤 경우든 유지됩니다.

더 나아가기: 매트릭스 실행, 폴더, 데이터 기반 테스트

기본 게이트가 설정되면, 몇 가지 플래그를 통해 YAML을 크게 추가하지 않고도 기능을 확장할 수 있습니다.

하나의 시나리오가 아닌 전체 기능 영역을 실행합니다. 폴더 내의 모든 시나리오를 실행하려면 -t <scenarioId>-f <folderId>로 바꾸거나, 선별된 스위트를 실행하려면 --test-suite <testSuiteId>를 사용합니다. 스위트는 특정 순서의 시나리오 세트를 하나의 논리적 작업으로 함께 실행하고 싶을 때 적절한 도구입니다. 테스트 스위트로 자동화된 API 테스트를 확장하는 가이드에서 언제 스위트를 사용해야 하는지 다룹니다.

여러 환경에서 병렬로 테스트합니다. 매트릭스는 여러 환경 ID에 걸쳐 동일한 작업을 동시에 실행합니다.

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run scenario against ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub는 매트릭스 값당 하나의 러너를 시작하므로, 스테이징 및 프로덕션이 동시에 테스트되고 각기 자체적인 성공/실패를 보고합니다.

데이터 파일에서 반복을 구동합니다. -d 플래그는 CSV 또는 JSON 파일의 행에 걸쳐 하나의 시나리오를 실행하며, 각 행을 별도의 통과로 처리합니다: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit. 이는 50개의 시나리오를 구축하지 않고도 50개의 입력에 대해 동일한 엔드포인트를 검증하는 방법입니다.

브랜치에 대해 실행합니다. 팀에서 Apidog의 브랜치 기능을 사용하는 경우, --branch <branchName>main 대신 특정 브랜치를 가리키도록 실행을 지정하여, 기능 브랜치의 PR이 해당 브랜치의 시나리오 정의에 대해 테스트할 수 있도록 합니다.

일반적인 CI 실패 문제 해결

작업은 녹색이지만 테스트가 실패했어야 합니다. apidog run 단계의 종료 코드가 실제로 GitHub에 도달하는지 확인하세요. 명령을 셸 파이프라인으로 래핑했거나 || true를 추가했다면, 0이 아닌 종료 코드가 무시되어 게이트가 자동으로 작동을 멈춥니다. 종료 코드를 가리는 모든 것을 제거하세요. 명령을 자체 줄에서 실행하거나 run: 블록의 마지막 명령으로 실행하여 해당 종료 상태가 단계의 종료 상태가 되도록 합니다.

인증 실패. 가장 흔한 원인은 비밀 이름이 일치하지 않는 것입니다. env: 키, 값 참조 ${{ secrets.APIDOG_ACCESS_TOKEN }}, 그리고 설정에서 생성한 비밀 이름이 모두 동일해야 합니다. 또한 Apidog에서 토큰을 저장한 이후 재생성되지 않았는지 확인하세요. 재생성하면 이전 토큰은 무효화됩니다.

로컬에서는 통과하지만 CI에서는 실패합니다. 실행 명령에 일시적으로 --verbose를 추가하세요. 러너가 보낸 전체 요청과 받은 전체 응답을 출력하는데, 이는 일반적으로 차이점을 밝혀냅니다. 흔히 사용자 머신에는 설정되어 있지만 CI 환경에는 없는 환경 변수이거나, 로컬 서비스와 다르게 작동하는 스테이징 서비스일 수 있습니다.

보고서가 아티팩트로 표시되지 않습니다. 실행 단계의 --out-dir과 업로드 단계의 path:가 동일한 디렉토리를 가리키는지 확인하고, 업로드 단계에 if: always()가 있는지 확인하세요. if: always()가 없으면, 테스트 실패 시 업로드를 건너뛰게 되어 가장 필요할 때 보고서를 잃게 됩니다.

러너가 API에 도달할 수 없습니다. 스테이징 또는 프로덕션 환경이 방화벽이나 VPN 뒤에 있다면, 공개 GitHub 호스팅 러너는 도달할 수 없습니다. 네트워크 내부에 자체 호스팅 러너가 필요하거나, GitHub의 IP 범위에 대한 허용 목록 항목이 필요합니다.

대안과의 비교

프레임워크를 사용하여 API 테스트를 코드로 작성하고, 이를 테스트 러너에 연결한 다음, Actions에서 호출할 수도 있습니다. 이 방법은 작동하지만, 이제 API와 팀이 API 도구에서 설계하는 모든 것과 동기화를 유지해야 하는 코드 스위트를 유지 관리해야 합니다. Apidog 접근 방식은 이러한 중복을 건너뜁니다. 팀이 앱에서 이미 유지 관리하는 시나리오가 CI에서 실행되는 테스트입니다.

워크플로 단계에서 원시 curl 호출을 스크립트화할 수도 있습니다. 단일 상태 확인에는 괜찮지만, 그 이상은 고통스럽습니다. CLI가 무료로 제공하는 어설션, 환경 전환, 보고 기능을 직접 만들어야 하기 때문입니다.

GitHub Actions만이 이 기능을 위한 유일한 플랫폼은 아닙니다. 동일한 apidog run 명령은 GitLab CI, Jenkins, CircleCI 또는 셸 명령을 실행하고 종료 코드를 읽을 수 있는 모든 러너에 통합될 수 있습니다. GitHub Actions가 사용자의 플랫폼이 아니라면, 여기의 패턴은 직접 적용됩니다. 플랫폼 간 관점을 보려면 CI/CD에서 API 테스트를 자동화하는 가이드를 참조하거나, Jenkins를 사용 중이라면 Jenkins와 Apidog 자동화 테스트를 통합하는 가이드를 참조하십시오.

실행할 시나리오를 구축하려면 Apidog를 다운로드하고, 앱에서 테스트를 설계한 다음, 시나리오의 CI/CD 탭에서 CLI 명령을 가져오십시오. 러너는 무료 npm 패키지입니다. 실행할 수 있는 것은 Apidog 프로젝트에 따라 다르지만, 명령줄 러너 자체는 별도의 유료 제품이 아닙니다.

마무리

설정은 보기보다 간단합니다. Apidog에서 시나리오를 구축하고, 하나의 액세스 토큰을 GitHub 비밀로 저장하고, 워크플로 파일에 몇 단계를 추가하면 됩니다. 그 후로는 모든 풀 리퀘스트가 API 테스트를 자동으로 실행하고, 실패한 엔드포인트는 병합 전에 검사를 빨간색으로 바꾸며, 무엇이 깨졌는지 확인해야 할 때마다 보고서가 Artifacts 탭에 준비되어 있습니다.

간단하게 유지되는 이유는 작업 분할에 있습니다. Apidog 앱이 테스트를 소유하고, CLI가 테스트를 실행하며, GitHub가 종료 코드를 읽습니다. 아무것도 중복되거나 동기화될 필요가 없습니다. 앱에서 어설션을 업데이트하면 다음 CI 실행에서 이를 사용합니다. 이것이 첫 프로덕션 사고 후에 조립하는 대신 프로젝트 첫날부터 이 작업을 수행할 가치가 있는 이유입니다.

버튼

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요