사용자 지정 GitHub 작업 만들기

8분

GitHub Actions는 사용자 자체 리포지토리를 이용해 편안하고 편리하게 코드를 클라우드로 옮길 수 있는 강력한 기능입니다. 여기에서는 다른 유형의 GitHub 작업과 사용자 지정 GitHub 작업을 만들기 위한 메타데이터, 구문, 워크플로 명령에 관해 알아봅니다.

GitHub 작업의 유형

Docker, JavaScript, 복합 실행 단계 작업의 세 가지 유형의 GitHub Actions를 표시하는 다이어그램.

Actions는 개발 워크플로를 사용자 지정하는 데 사용할 수 있는 개별 작업입니다. 리포지토리와 상호 작용하는 사용자 지정 코드를 작성하여 사용자 지정 작업을 수행하거나, GitHub 커뮤니티에서 공유하는 작업을 사용하여 사용자 고유의 작업을 만들 수 있습니다. 다양한 작업을 탐색하면 Docker 컨테이너 작업, JavaScript 작업과 복합 실행 단계 작업라는 세 가지 유형의 작업이 있음을 알게 됩니다. 각 작업 유형을 자세히 살펴보겠습니다.

Docker 컨테이너 작업

Docker 컨테이너는 GitHub Actions 코드로 환경을 패키지합니다. 이는 모든 종속성이 해당 컨테이너 내에 있기 때문에 작업이 일관되고 안정적인 환경에서 실행됨을 의미합니다. 작업을 특정 환경 구성에서 실행해야 하는 경우에는 운영 체제 및 도구를 사용자 지정할 수 있는 Docker 컨테이너를 사용하는 것이 좋습니다. 단점은 컨테이너를 빌드하고 검색해야 하므로 Docker 컨테이너 작업이 JavaScript 작업보다 느린 경우가 있다는 것입니다.

Docker 컨테이너 작업을 빌드하기 전에 환경 변수 및 Docker 컨테이너 파일 시스템을 사용하는 방법에 대한 기본적인 이해가 있어야 합니다. Docker 컨테이너 작업을 빌드하기 위한 단계는 최소한의 수준으로 간단합니다.

Dockerfile을 만들어 Docker 이미지를 조합하는 명령을 정의합니다.
action.yml 메타데이터 파일을 만들어 작업의 입력과 출력을 정의합니다. 파일에서 runs: using: 값을 docker로 설정하고 runs: image: 값을 Dockerfile로 설정합니다.
entrypoint.sh 파일을 만들어 Docker 이미지를 설명합니다.
다음 action.yml, entrypoint.sh, Dockerfile, README.md 파일을 사용하여 작업을 GitHub에 커밋하고 밀어넣습니다.

JavaScript 작업

JavaScript 작업은 실행기 머신에서 직접 실행할 수 있으며, 작업을 실행하는 데 사용하는 환경에서 작업 코드를 분리할 수 있습니다. 이로 인해 작업 코드가 단순화되고 Docker 컨테이너 내의 작업보다 빠르게 실행될 수 있습니다.

패키지된 JavaScript 작업을 만들고 사용하기 위한 필수 조건으로 npm이 포함된 Node.js를 다운로드해야 합니다. 선택적인 (하지만 당사에서 권장하는) 단계는 좀 더 일관적이고 신속하게 JavaScript 작업을 빌드할 수 있는 Node.js 패키지의 컬렉션인 GitHub Actions Toolkit Node.js를 사용하는 것입니다.

JavaScript 작업을 빌드하는 단계는 최소 수준이며 간단합니다.

작업의 입력 및 출력을 정의하는 action.yml 메타데이터 파일을 만들고 이 JavaScript 작업을 실행하는 방법을 작업 실행기에 알려줍니다.
도구 키트 패키지, 라우팅, 작업의 기타 기능에 대한 컨텍스트 정보를 사용하여 index.js 파일을 만듭니다.
다음 action.yml, index.js, node_modules, package.json, package-lock.json, README.md 파일을 사용하여 작업을 GitHub에 커밋하고 밀어넣습니다.

복합 실행 단계 작업

복합 실행 단계 작업을 사용하면 셸 스크립트를 사용하여 작업을 다시 사용할 수 있습니다. 동일한 작업 내에서 여러 셸 언어를 혼합할 수도 있습니다. 여러 작업을 자동화하는 다양한 셸 스크립트가 있는 경우, 이제 이러한 스크립트를 작업으로 쉽게 전환하고 다른 워크플로에 다시 사용할 수 있습니다. 때로는 JavaScript를 사용하거나 코드를 Docker 컨테이너에 래핑하는 것보다 셸 스크립트를 작성하기가 더 쉽습니다.

작업을 만드는 데 필요한 메타데이터 및 구문

GitHub 작업을 만들거나 검토할 때 바람직한 첫 번째 단계는 action.yml 파일을 검토하여 작업에서 요구하는 입력, 출력, 설명, 실행, 기타 구성 정보를 평가하는 것입니다. 이러한 매개 변수 중 일부는 필수이고 일부는 선택 사항입니다. 이 action.yml 파일은 작업에 대한 다음 정보를 정의합니다.

매개 변수	설명	필수
Name	작업의 이름입니다. 작업의 동작을 시각적으로 식별하는 데 도움이 됩니다.	예
설명	작업 수행에 대한 요약입니다.	예
입력	입력 매개 변수를 사용하면 런타임 중에 작업에서 사용할 데이터를 지정할 수 있습니다. 이러한 매개 변수는 실행기의 환경 변수가 됩니다.	아니요
출력	출력 매개 변수를 사용하면 이러한 출력을 정의하는 작업이 실행된 후 나중에 워크플로의 후속 작업에서 사용할 수 있는 데이터를 지정할 수 있습니다.	아니요
실행	작업이 실행될 때 실행할 명령입니다.	예
브랜딩	GitHub Marketplace에서 작업을 개인 설정하고 구분하기 위한 배지를 만드는 데 사용할 색상 및 깃털 아이콘입니다.	아니요

입력

Inputs는 작업에서 런타임 중에 사용할 데이터를 지정할 수 있는 매개 변수입니다. GitHub는 이러한 입력 매개 변수를 환경 변수로 저장합니다.

다음은 작업에 대한 입력 목록의 예입니다. firstNameStudent 입력은 선택 사항이지만 studentGrade 입력은 필수입니다.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

출력

Outputs는 데이터를 선언할 수 있는 매개 변수입니다. 워크플로에서 나중에 실행되는 작업은 이전에 실행된 작업에서 선언된 출력 데이터를 사용할 수 있습니다.

다음 예는 학생들의 평균 등급을 선언하는 간단한 출력입니다.

outputs:
  average:
    description: 'The average grade of the students'

실행

이전에 학습한 것처럼 작업에는 작업을 실행하는 데 필요한 명령을 정의하는 runs 문이 있어야 합니다. 작업을 만드는 방법, 즉 Docker 컨테이너, JavaScript 또는 복합 실행 단계 중 무엇을 사용하는지에 따라 runs 구문이 다르게 정의됩니다.

Docker 작업에 대한 `runs`

Docker 컨테이너 작업을 수행하려면 runs 문이 다음 인수를 사용하여 Docker 작업에서 사용하는 이미지를 구성해야 합니다.

using: Docker 컨테이너 작업을 실행하려면 docker 설정해야 합니다.
image: 작업을 실행하는 컨테이너로 사용되는 Docker 이미지입니다.

runs:
  using: 'docker'
  image: 'Dockerfile'

JavaScript 작업에 대한 `runs`

JavaScript 작업을 수행하려면 runs 문이 다음 두 가지 인수를 사용해야 합니다.

using: main정의된 대로 코드를 실행하는 데 사용되는 애플리케이션입니다.
main: 작업 코드가 포함된 파일입니다. using 정의된 애플리케이션이 이 파일을 실행합니다.

예를 들어 다음은 Node.js를 사용하는 JavaScript 작업에 대한 runs 문입니다.

runs:
  using: 'node12'
  main: 'main.js'

복합 실행 단계 작업에 대한 `runs`

복합 실행 단계 작업을 수행하려면 runs 문이 다음 세 가지 인수를 사용해야 합니다.

using: 복합 실행 단계를 실행하려면 "composite" 설정해야 합니다.
steps: 작업을 실행하는 단계를 실행합니다.
steps[*].run: 실행하려는 명령(작업 리포지토리의 인라인 또는 스크립트일 수 있습니다).

예를 들어 다음은 파일 경로 runs에서 스크립트를 실행하는 복합 실행 단계 작업에 대한 /test/script/sh 문입니다.

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

브랜딩

선택적이지만 재미있는 기능으로 작업의 배지를 사용자 지정할 수 있습니다. 이 배지는 GitHub Marketplace의 작업 이름 옆에 표시됩니다. 색상 및 깃털 아이콘을 사용하여 배지를 만들 수 있습니다. 브랜딩의 경우 사용할 아이콘과 색상을 지정해야 합니다.

branding:
  icon: 'shield'  
  color: 'blue'

다음은 GitHub Marketplace의 체크 아웃 작업 배지 예시입니다.

GitHub Marketplace의 작업 브랜딩을 보여 주는 스크린샷

워크플로 명령

단계에 적합한 작업을 찾기만 한다면 워크플로를 만드는 것은 매우 간단합니다. 원하는 결과를 얻으려면 고유한 작업을 만들어야 하는 경우도 있지만, 워크플로 명령을 사용하여 워크플로에 다른 사용자 지정 수준을 추가할 수 있습니다.

워크플로 명령을 사용하면 서식이 지정된 텍스트 줄을 콘솔로 출력하여 GitHub Actions 실행기 머신과 통신할 수 있습니다. 이러한 워크플로 명령은 셸 명령과 함께 사용하거나 사용자 지정 작업 내에서 사용할 수 있습니다. 워크플로 명령은 워크플로 단계 간에 정보를 공유하고, 디버그 또는 오류 메시지를 콘솔에 출력하며, 환경 변수를 설정하고, 출력 매개 변수를 설정하거나, 시스템 경로에 추가할 수 있어 매우 유용합니다.

대부분의 워크플로 명령은 다음와 같은 특정 형식으로 echo 명령을 사용하지만, 파일에 작성하여 호출할 수 있는 명령도 있습니다.

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

다음은 콘솔에 디버그 메시지, 정보 메시지, 오류 메시지 또는 경고 메시지를 출력하기 위한 몇 가지 기본 메시지 로깅 예입니다.

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

오류가 발생한 파일 이름(file), 줄 번호(line), 열(col) 번호를 사용하여 로그에 출력하는 메시지를 만들 수도 있습니다. 경고 메시지는 ‘경고’ 텍스트와 함께 노란색 강조 표시로 표시되고 오류 메시지는 ‘오류’ 텍스트와 함께 빨간색 강조 표시로 표시됩니다.

echo "::error file=app.js,line=10,col=15::Something went wrong"

이러한 워크플로 명령은 한 줄에 있어야 합니다. 쉼표 및 줄 바꿈과 같은 구문 분석을 방해하는 문자는 URL로 인코딩해야 합니다.

예를 들어 다음 텍스트는 여러 줄 메시지입니다.

This text spans
across multiple lines

이 메시지는 다음과 같이 인코딩되어야 합니다.

This text spans%0Aacross multiple lines

워크플로 명령 외에도 종료 코드를 설정하여 작업 상태를 설정할 수 있습니다. 워크플로에서 작업을 수행할 때 실패한 종료 코드가 모든 동시 작업을 중지하고 이후 작업을 모두 취소해 버리기 때문에 이 설정은 매우 중요합니다. JavaScript 작업을 만드는 경우, 작업 도구 키트 @actions/core 패키지를 사용하여 메시지를 로그하고 실패 종료 코드를 설정할 수 있습니다. Docker 컨테이너 작업을 만드는 경우 entrypoint.sh 스크립트에서 실패 종료 코드를 설정할 수 있습니다.