GitHub Actions에서 워크플로 관리 및 디버그

  • 10분

개발자가 코드 베이스에 변경 내용을 추가할 때마다 기능이 업데이트되도록 코드 빌드 및 게시 프로세스를 자동화하는 것이 목표입니다.

이 프로세스를 구현하려면 다음 방법을 알아봅니다.

  • 워크플로를 트리거한 이벤트를 식별합니다.
  • GitHub Actions 워크플로 로그를 사용합니다.
  • 빌드 아티팩트 저장 및 액세스
  • 검토 후 끌어오기 요청에 레이블 추가를 자동화합니다.

워크플로를 트리거한 이벤트 식별

GitHub Actions 워크플로를 트리거한 내용을 이해하는 것은 CI/CD 파이프라인을 디버깅, 감사 및 개선하는 데 매우 중요합니다. 트리거 유형에는 브랜치에 대한 푸시, 생성되거나 업데이트된 풀 요청, 예약된 작업 또는 수동 실행이 포함됩니다. 워크플로 실행, 리포지토리 변경, 관련 GitHub 문제 또는 끌어오기 요청을 검사하여 트리거 이벤트를 식별할 수 있습니다.

푸시, 끌어오기 요청, 일정 및 수동 디스패치와 같은 GitHub Actions의 다양한 워크플로 트리거를 보여 주는 다이어그램

워크플로 트리거란?

워크플로 트리거는 워크플로를 실행하게 하는 이벤트입니다. GitHub는 다음을 비롯한 다양한 유형의 트리거를 지원합니다.

  • push 또는 pull_request (코드 변경에 따라)
  • workflow_dispatch (수동 트리거)
  • schedule(cron 작업)
  • repository_dispatch (외부 시스템)
  • 문제, 토론 및 끌어오기 요청 이벤트(예: issues.opened, pull_request.closed)

트리거 이벤트 식별

다음과 같은 여러 가지 방법으로 워크플로 트리거 이벤트를 식별할 수 있습니다.

  • GitHub Actions UI를 사용합니다.

    1. 리포지토리에서 작업 탭을 선택합니다.
    2. 워크플로 실행을 선택합니다.

    워크플로 실행 요약의 맨 위에 이벤트 유형(예: push, pull_request또는 workflow_dispatch)이 나타납니다.

  • github.event_name를 로그 또는 워크플로에서 사용합니다.

    • GitHub는 워크플로 실행 중에 컨텍스트 데이터를 노출합니다. 변수는 github.event_name 워크플로를 트리거한 이벤트를 알려줍니다.

    • 디버깅을 위한 단계에서 정보를 인쇄할 수 있습니다.

      -name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"

  • 워크플로 실행 세부 정보 사용:

    • API 사용과 같이 프로그래밍 방식으로 워크플로 실행을 검사하는 경우 실행 개체에는 트리거를 event 지정하는 속성이 포함됩니다.
    • 커밋의 SHA(Secure Hash Algorithm), 행위자 및 타임스탬프를 찾아 트리거의 원인을 추적할 수 있습니다.

리포지토리 효과에서 트리거 유추

워크플로 실행에 직접 액세스할 수는 없지만 리포지토리 활동에 따라 워크플로 실행을 트리거한 항목을 유추하려고 합니다.

관찰된 동작 트리거 이벤트
새 커밋이 main에 푸시되고 워크플로가 실행되었습니다. push 이벤트
끌어오기 요청이 열리거나 업데이트되었습니다. pull_request 이벤트
기여자가 워크플로를 수동으로 실행했습니다. workflow_dispatch
워크플로는 특정 시간에 매일 실행됩니다. schedule (cron)
워크플로는 외부 서비스 호출 후에 실행되었습니다. repository_dispatch
레이블 또는 주석이 문제에 추가되었을 때 워크플로가 실행되었습니다. issues.* 이벤트

타임스탬프, 끌어오기 요청 활동 및 커밋 기록을 검토하여 워크플로가 실행된 작업을 정확히 파악할 수 있습니다.

워크플로를 트리거한 내용을 식별하는 방법을 요약하려면 다음을 수행합니다.

  • 작업 탭에서 워크플로 실행 요약을 확인 합니다 .
  • 가시성을 위해 워크플로의 내부에서 github.event_name을 인쇄하거나 기록합니다.
  • 타임스탬프 및 리포지토리 작업(커밋, 끌어오기 요청, 문제)을 비교하여 트리거를 유추합니다.
  • 자세한 조사를 위해 전체 event 컨텍스트를 사용합니다.

이러한 방법은 개발 및 배포 파이프라인 전체에서 워크플로 안정성을 디버그, 감사 및 개선하는 데 도움이 됩니다.

구성 파일을 읽어 워크플로 효과 이해

구성 파일을 읽는 워크플로의 효과를 이해하려면 저장된 .yml파일의 .github/workflows/ 구조와 내용을 분석합니다.

워크플로 구성 파일은 워크플로에 대한 다음 정보를 지정합니다.

  • (on 섹션에서) 실행될 때.
  • 작업 수행 방식 (jobs 및 steps에)
  • 실행 위치( runs-on 섹션).
  • 실행 이유(테스트, 배포, 린팅 등의 목적)
  • 특정 조건(환경, 필터, 논리)에서 동작하는 방식

워크플로 효과 해석

  1. 트리거를 식별합니다.

    워크플로를 시작한 작업을 식별하려면 워크플로 섹션을 on 참조하세요.

    다음은 그 예입니다.

    on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:

    이 예제 워크플로:

    • 코드가 주 분기(push)로 푸시될 때 자동으로 실행됩니다.
    • 끌어오기 요청을 만들거나 업데이트할 때 실행됩니다(pull_request).
    • 사용자(workflow_dispatch)가 수동으로 트리거할 수 있습니다.

  2. 워크플로 작업 및 단계를 식별합니다.

    워크플로가 수행하는 작업을 확인하려면 워크플로의 jobs 섹션 및 steps 섹션을 참조하세요.

    다음은 그 예입니다.

    jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

    이 예제 워크플로:

    • Linux 가상 환경(runs-on)을 사용합니다.
    • 리포지토리의 코드(steps>name)를 확인합니다.
    • 프로젝트 종속성(steps>name)을 설치합니다.
    • 자동화된 테스트(steps>name)를 실행합니다.

  3. 워크플로의 목적과 결과를 평가합니다.

    구성 파일을 읽어 워크플로의 의도된 결과를 설명할 수 있습니다.

    "이 워크플로는 CI(연속 통합) 파이프라인입니다. 리포지토리에 푸시되거나 끌어오기 요청을 통해 제출된 새 코드가 자동으로 테스트됩니다. 테스트가 실패하면 GitHub 워크플로 UI가 코드 품질을 유지하는 데 도움이 되도록 이 결과를 표시합니다."

  4. 워크플로 실행 방식에 영향을 주는 선택적 기능을 식별하거나 설정합니다.

    • env 는 환경 변수를 설정합니다.
    • if 는 조건이 충족되는 경우에만 특정 단계를 실행하는 조건부 논리를 추가합니다.
    • timeout-minutes 또는 continue-on-error 워크플로 실행 및 오류 처리를 설정합니다.

실패한 워크플로 실행 진단

  1. 리포지토리에서 작업 탭으로 이동합니다.

  2. 실패한 실행(일반적으로 빨간색 X로 표시됨)을 찾습니다.

  3. 실패한 워크플로를 선택하여 실행 요약을 엽니다.

  4. 워크플로 로그에서 오류를 검토합니다.

    1. 실행 요약에서 각 작업 및 단계를 확장하여 실패를 나타내는 작업이나 단계를 확인합니다.

    2. 작업 또는 단계를 선택하여 로그를 봅니다.

    3. 살펴볼 항목:

      • 오류 메시지
      • 스택 추적
      • 종료 코드

    예를 들어 실패한 테스트가 npm ERR! Test failed 또는 exit code 1으로 표시될 수 있다.

  5. 워크플로 구성 파일을 확인합니다.

    .yml 파일을 사용하여 다음을 확인합니다.

    • 각 단계는 무엇을 하려고 합니까?
    • 실행에 영향을 주는 환경 변수(env) 또는 조건부(if)가 있는 경우
    • 종속성 누락, 구문 오류 또는 잘못 구성된 단계로 인해 오류가 발생하는 경우

    단계가 실패하면 다음 원인을 확인합니다.

    • 이전 단계에서 종속성이 성공적으로 설치되었나요?
    • 테스트 파일이 존재하고 로컬로 전달합니까?

일반적인 실패 시나리오

다음 표에서는 일반적인 워크플로 실패 시나리오에 대해 설명합니다.

증상 가능한 원인
단계가 실패하고 l을 반환합니다.command not found 종속성 누락 또는 잘못된 설정
npm install 실패. 손상된 package-lock.json 파일 또는 네트워크 문제
테스트 단계 실패 단위 테스트 문제, 누락된 구성 파일 또는 잘못된 테스트 구문
Permission denied가 나타납니다. 잘못된 파일 사용 권한 또는 누락된 비밀

GitHub에서 워크플로 로그에 액세스하는 방법 식별

  1. 리포지토리에서 작업 탭으로 이동합니다.

  2. 워크플로 목록에서 관련 워크플로를 선택합니다.

    예를 들어 파일에 다음 코드가 있는 경우 .ymlCI 워크플로 라는 링크가 목록에 나타납니다.

    name: CI Workflow

  3. 특정 실행을 선택합니다.

    상태를 표시하는 실행 목록에서 검사하려는 특정 실행의 타임스탬프 또는 커밋 메시지를 선택합니다.

  4. 각 작업 및 단계를 확장합니다.

    실행 요약 페이지에는 빌드 또는 테스트와 같은 워크플로 파일에 정의된 작업이 표시됩니다.

    1. 작업을 선택하여 확장합니다.
    2. 작업 내에서 "종속성 설치" 또는 "테스트 실행"과 같은 개별 단계를 확장합니다.

  5. 로그 출력을 봅니다.

    콘솔 로그, 오류 메시지 및 디버그 정보를 포함하여 전체 로그 출력을 보려면 워크플로 단계를 선택합니다. 로그를 복사, 검색 및 다운로드할 수 있습니다.

다음 표에서는 워크플로 로그에 액세스하기 위해 수행하는 단계를 요약합니다.

조치 목적
작업 탭 모든 워크플로 실행을 봅니다.
워크플로 이름 선택 워크플로에 따라 실행을 필터링합니다.
실행 선택 특정 작업 및 단계 결과를 참조하세요.
단계 확장 자세한 로그를 봅니다.
로그 다운로드 오프라인 또는 팀 문제 해결을 위한 로그를 다운로드합니다.

빌드에 대한 작업 로그

워크플로가 실행되면 발생한 작업과 오류 또는 테스트 실패에 대한 세부 정보가 포함된 로그가 생성됩니다.

오류가 발생하거나 테스트에 실패하면 녹색 확인 표시 대신 빨간색 X가 로그에 나타납니다. 오류 또는 실패의 세부 정보를 검사하여 발생한 결과를 조사할 수 있습니다.

실패한 테스트에 대한 세부 정보가 포함된 GitHub Actions 로그의 스크린샷

아티팩트 작업

워크플로에서 로그 항목 이외의 항목을 생성하는 경우 제품을 아티팩트라고 합니다. 예를 들어 Node.js 빌드는 배포할 수 있는 Docker 컨테이너를 생성합니다. 컨테이너는 작업/업로드 아티팩트 작업을 사용하여 스토리지에 업로드할 수 있는 아티팩트입니다 . 나중에 작업/다운로드 아티팩트(download-artifact)를 사용하여 스토리지에서 아티팩트 다운로드할 수 있습니다.

아티팩트를 저장하면 작업 간에 유지됩니다. 각 작업은 VM의 새 인스턴스를 사용하므로 VM에 저장하여 아티팩트를 다시 사용할 수 없습니다. 다른 작업에 아티팩트가 필요한 경우 한 작업의 스토리지에 아티팩트를 업로드하고 다른 작업에 대해 다운로드할 수 있습니다.

아티팩트 스토리지

아티팩트는 GitHub의 스토리지 공간에 저장됩니다. 이 공간은 공용 리포지토리에 대해 무료이며, 일부 스토리지는 계정에 따라 프라이빗 리포지토리에 대해 무료입니다. GitHub는 90일 동안 아티팩트를 저장합니다.

다음 워크플로 코드 조각에서 actions/upload-artifact@main 작업에 path 특성이 있음을 주의하십시오. 이 특성의 값은 아티팩트 저장 경로입니다. 이 예제에서는 공용/ 디렉터리에 모든 항목을 업로드하도록 지정합니다. 단일 파일만 업로드하려면 public/mytext.txt같은 항목을 사용합니다.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

테스트를 위해 아티팩트 다운로드를 수행하려면 빌드가 성공적으로 완료되고 아티팩트가 업로드되어야 합니다. 다음 코드에서는 테스트 작업이 빌드 작업에 따라 달라지게 지정합니다.

test:
    needs: build
    runs-on: ubuntu-latest

다음 워크플로 코드 조각에서는 아티팩트 다운로드를 수행합니다. 이제 테스트 작업은 아티팩트 테스트를 위해 사용할 수 있습니다.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

워크플로에서 아티팩트 사용에 대한 자세한 내용은 워크플로 데이터를 아티팩트로 저장을 참조하세요.

워크플로를 사용하여 GitHub에서 검토 자동화

GitHub 이벤트 등을 pushpull-request통해 워크플로를 시작하는 것 외에도 일정에 따라 또는 GitHub 외부의 일부 이벤트 후에 워크플로를 실행할 수 있습니다.

검토자가 끌어오기 요청을 승인한 후와 같이 사용자가 특정 작업을 완료한 후에만 워크플로를 실행할 수 있습니다. 이 시나리오에서는 pull-request-review를 트리거할 수 있습니다.

수행할 수 있는 또 다른 작업은 끌어오기 요청에 레이블을 추가하는 것입니다. 이 경우 pullreminders/label-when-approved-action 작업을 사용합니다.

다음은 그 예입니다.

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

블록에서 env 작업에 대한 환경 변수를 설정합니다. 예를 들어 워크플로를 실행하는 데 필요한 승인자 수를 설정할 수 있습니다. 이 예제에서는 하나입니다. secrets.GITHUB_TOKEN 작업이 레이블을 추가하여 리포지토리를 변경해야 하므로 인증 변수가 필요합니다. 마지막으로 추가할 레이블의 이름을 입력합니다.

레이블을 추가하는 것은 병합과 같은 다른 워크플로를 시작하는 이벤트일 수 있습니다. GitHub Actions에서 지속적인 업데이트를 사용하는 방법에 대해 설명하는 다음 모듈에서 이 이벤트를 다룹니다.