워크플로우 구성

당신이 레포지토리에 관해 쓰기, admin 권한이 있다면, 워크플로우를 제작, 보기, 또는 편집을 할 수 있습니다. 당신이 포함한 액션의 타입에 따라 워크플로우를 커스터마이징 할 수 있습니다.

워크플로우에 대하여#

워크플로우들은 커스텀한 자동화 프로세스들로, 당신이 깃허브의 프로젝트를 빌드, 테스트, 패키징, 릴리즈, 또는 배포하기 위해 설정할 수 있는 것들입니다. 폭 넓은 범위의 툴들과 서비스와 함께 SDLC를 자동화 할 수 있습니다. 더 많은 정보를 보려면 깃허브 액션에 대하여를 참고하세요.

하나의 레포지토리에 하나 이상의 워크플로우를 생성 가능합니다. 반드시 레포지토리의 루트 디렉토리의 .github/workflows 디렉토리에 워크플로우들을 보관하여야 합니다.

워크플로우는 최소한 하나의 잡(job)을 가져야하며, 잡은 개별적인 태스크를 수행하는 스텝(step, 단계)의 모임을 포함하는 개념입니다. 스텝에서는 커맨드를 실행하거나 액션을 사용할 수 있습니다. 액션은 생성하거나 깃허브 커뮤니티에 공유할 수 있고, 필요에 따라 커스터마이즈 할 수 있습니다.

깃허브 이벤트가 발생할 때, 스케줄에서, 혹은 외부의 이벤트로부터 워크플로우의 실행을 구성(configure)할 수 있습니다.

YAML 문법을 사용하여 워크플로우를 구성할 필요가 있으며, 워크플로우 파일 형태로 레포지토리에 저장해야합니다. 한번 성공적으로 YAML 워크플로우 파일이 만들어지고, 워크플로우가 트리거(발동, 발생) 된다면, 당신은 빌드 로그들, 테스트 결과들, 아티팩트들, 그리고 상태들을 매 스텝마다 볼 수 있을 것입니다. 더 많은 정보는 "워크플로우 실행 관리"를 참고하세요.

또한 스테이터스 업데이트 알림을 받을 수 있습니다. 알림에 관한 더 많은 정보는 "알림을 위한 딜리버리 메소드 선택"을 참고하세요.

사용 제한은 각각의 워크플로우들에게 적용됩니다. "워크플로우의 사용제한"을 참고하십시오.

워크플로우 파일 만들기#

높은 수준에서, 이것들은 워크플로우 파일들을 추가하기 위한 단계입니다. 자세한 예시는 다음과 같습니다.

레포지토리의 루트 디렉토리에 .github/workflows 디렉토리를 만든다.
.github/workflows 안에, .yml 또는 .yaml 파일을 추가한다. 예) .github/workflows/continuous-integration-workflow.yml
"워크플로우 문법"들을 사용해 액션을 트리거하기 위한 이벤트들을 선택하거나, 액션들을 추가하거나, 워크플로우를 커스터마이즈한다.
워크플로우를 실행시킬 브랜치로 바꾼 내용들을 커밋한다.

예시#

name: Greet Everyone
# 이 워크플로우는 푸쉬할 때 트리거됩니다.
on: [push]

jobs:
  build:
    # 잡의 이름은 Greeting
    name: Greeting
    # 리눅스 환경에서 실행합니다.
    runs-on: ubuntu-latest
    steps:
      # 이 스텝에서 깃허브의 hello-world-javascript-action을 사용합니다: https://github.com/actions/hello-world-javascript-action
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
        id: hello
      # 이 스텝에서 전 스텝의 액션의 결과(여기서는 시간)를 출력합니다.
      - name: Echo the greeting's time
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

이벤트로 워크플로우 트리거하기#

다음이 발생할 때 워크플로우를 시작하도록 구성할 수 있습니다:

깃허브에서 push 나 issue 만들기, pull 같은 이벤트가 발생할 때
스케줄(예정)된 이벤트가 시작될 때
외부이벤트가 발생할 때

깃허브 이벤트 후#

깃허브에서 이벤트 발생후 트리거 하기 위해서는 on:와 이벤트 값을 워크플로우 이름 다음에 추가합니다. 예를들면, 다음의 워크플로우는 어떤 브랜치든 레포지토리 내에서 푸쉬될 때 트리거 됩니다.

name: descriptive-workflow-name
on: push

스케줄#

워크플로우를 스케쥴하기 위해 Posix cron 문법을 사용할 수 있습니다. 스케쥴된 워크플로우 실행을 설정할 수 있는 가장 짧은 간격은 5분입니다. 예를들면, 한 시간마다 트리거 된다고 가정할 경우,

on:
  schedule:
    - cron: '0 * * * *'

외부이벤트#

외부이벤트가 발생했을 때 워크플로우를 트리거 하기 위해서는, repository_dispatch라는 웹훅 이벤트를 불러야(invoke) 합니다. "Create a repository dispatch event" REST API 엔드포인트를 불러야(call) 방금의 웹훅 이벤트가 불러집니다. "레포지토리 디스패치 이벤트 만들기"를 참고하세요.

더 많은 정보는 "이벤트들"을 참고하세요.

특정 브랜치, 태그, 그리고 경로들에 대한 필터링#

특정 브랜치에 대하여만 워크플로우를 실행시킬 수도 있습니다.

예를 들면, master 브랜치의 test 디렉토리 안에 있는 파일들을 푸쉬할 때 또는 v1 태그로 푸쉬할 때에는,

on:
  push:
    branches:
      - master
    tags:
      - v1
    # file paths to consider in the event. Optional; defaults to all.
    paths:
      - 'test/*'

더 많은 정보는 "on.<push|pull_request>.<branches|tags>" 그리고 "on.<push|pull_request>.paths."를 참조하세요.

가상환경 설정하기#

github-hosted 가상 환경이나 독커 컨테이너(Docker Container)에서 워크플로우를 실행할 수 있습니다. 그러므로 워크플로우 안에 있는 각 잡에 대하여 가상환경을 지정해야합니다.

가상 환경의 OS(operating system), 툴, 패키지, 그리고 설정들을 지정하기 위해서는 워크플로우 파일 내에 특정한 문법을 사용하여야합니다.

더 많은 정보는 github-hosted-runners를 위한 가상환경를 참고하세요.

가상 호스트 머신(virtual host machines)#

리눅스, 윈도우, 맥을 포함한 다양한 종류와 버젼의 가상 호스트 머신들을 선택할 수 있습니다. 워크플로우 안의 각 잡은 같은 가상환경에서 실행되며, 해당 잡의 액션들이 파일 시스템을 사용하여 정보 공유를 할 수 있도록 허용합니다.

가상환경의 새로운 인스턴스에서 잡을 실행시키기 위해선 가상 호스트를 지정해야합니다.

runs-on: ubuntu-18.04

더 많은 정보는 "워크플로우 문법"를 참고하세요.

빌드 매트릭스(build matrix) 구성#

여러 OS, 플랫폼, 그리고 언어 버전을 동시에 테스트하기 위해, 빌드 매트릭스를 구성할 수 있습니다.

빌드 매트릭스는 테스트할 가상 환경을 위해 다양한 구성(configuration)을 제공합니다. 예를 들면 워크플로우는 하나 이상의 언어, OS, 혹은 툴의 지원하는 버전에서 실행할 수 있습니다. 각 구성에 대하여 잡의 복사본을 실행하고 상태를 보고합니다.

빌드 매트릭스는 stratege: 하의 구성 옵션들에 어레이형태로 지정할 수 있습니다. 예를들면, 다음의 빌드 매트릭스는 잡을 다양한 버전의 node.js와 우분투에서 실행시킬 것입니다.

OS의 매트릭스를 정의할 때에는, 하드코딩된 OS 이름 대신 반드시 runs-on 키워드를 통해 해당 잡의 OS를 설정해야합니다. OS 이름에 접근 할때에는 matrix.os 컨텍스트 파라미터를 runs-on에 설정해야합니다. 더 많은 정보는 컨텍스트와 표현식 문법을 참고하세요.

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]

더 많은 정보는 "워크플로우 문법"를 참고하세요.

체크아웃 액션 사용하기#

워크플로우에서 사용할 수 있는 몇몇 표준 액션들이 있습니다. 체크아웃 액션은 다음의 상황에서 다른 액션들 전에 반드시 포함되어야 하는 표준 액션입니다.

워크플로우가 레포지토리의 코드를 요구 할 때, 예를들면 레포지토리를 빌드하고 테스트하고 잇는 중이거나 CI를 사용중일 때.
최소 하나의 액션이 같은 레포지토리 안에서 정의될 때, 더 자세한 정보는 아래의 액션 참조하기 부분 혹은 원문링크를 참고하세요.

표준 체크아웃 액션을 특별한 지정없이 사용하려면,

- uses: actions/checkout@v1

이 예에서는 v1을 사용하면 안정적인 버전의 체크아웃 액션을 사용하게 됩니다.

레포지토리를 얕은 클론 하거나, 최신 버전의 레포지토리만 복사하려면 with를 사용하여 fetch-depth를 설정하세요.

- uses: actions/checkout@v1
  with:
    fetch-depth: 1

더 많은 정보를 위해, "체크아웃 액션"을 참고하세요.

액션의 종류 선택#

프로젝트에 맞게 사용할 수 잇는 다양한 종류의 액션이 있습니다.

독커 컨테이너(docker container) 액션
자바스크립트(javascript) 액션

더 자세한 정보는, "액션에 대하여"를 참고하세요.

액션의 타입을 선택할 때, 퍼블릭 레포지토리나 도커 허브를 둘러보고, 커스터마이즈를 하는 것을 권장합니다.

당신은 깃허브의 github.com/actions 조직에 의해 빌드된 액션을 찾아보고(browse) 사용할 수 있습니다. 도커 허브에 방문하려면 "Docker Hub"를 참고하세요.

워크플로우에서 액션 참조 (referencing action)#

액션을 올바르게 참조하기 위해서는 액션이 어디서 정의되었는지를 고려해야합니다.

워크플로우가 사용할 수 있는 액션은 다음에서 정의됩니다.

퍼블릭 레포지토리
워크플로우 파일이 액션을 참조하는 곳과 같은 레포지토리
도커 허브의 퍼블리시 된 도커 컨테이너 이미지

프라이빗 레포지토리에 정의된 액션을 사용하기 위해서는 워크플로우 파일과 액션이 반드시 같은 레포지토리 안에 있어야합니다. 워크플로우는 다른 곳에 있는 프라이빗 레포지토리에 정의된 액션을 사용할 수 없습니다. 아무리 같은 조직(organization)안에 있어도요.

액션이 업데이트 되었어도 워크플로우를 안정적으로 유지하기 위해, 워크플로우 안에 있는 Git ref나 Docker tag number를 지정함으로써 사용하고 있는 버전의 액션을 참조할 수 있습니다. 예를 들면 "워크플로우 문법"을 참고하세요.

더 자세한 구성 옵션들은 "워크플로우 문법"을 참고하세요.

퍼블릭 레포지토리의 액션 참조하기#

만약 퍼블릭 레포지토리에 정의되었다면, {owner}/{repo}@{ref} 또는 {owner}/{repo}/{path}@{ref}의 형식으로 액션을 참조해야만 합니다.

jobs:
  my_first_job:
    name: My Job Name
      steps:
        - uses: actions/setup-node@v1
          with:
            node-version: 10.x

완성된 워크플로우 예시를 보고 싶다면, "setup node" 템플릿 레포지토리를 참조하세요.

같은 곳에 있는 액션 참조하기#

워크플로우 파일과 같은 레포지토리에 정의되어 있다면, {owner}/{repo}@{ref} 또는 ./path/to/dir 의 형식을 이용하여 참조할 수 있다.

레포지토리 파일 구조 예시:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

워크플로우 파일 예시:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # 이 스텝은 레포지토리의 복사본을 체크아웃합니다.
      - uses: actions/checkout@v1
      # 이 스텝은 액션을 포함한 디렉토리를 참조합니다.
      - uses: ./.github/actions/hello-world-action

도커허브의 컨테이너 참조#

만약 액션이 도커 허브의 퍼블리시 된 도커 컨테이너 이미지에 정의 되어있다면, 반드시 워크플로우 안에서 다음의 형식으로 참조해야 합니다: docker://{image}:{tag} 코드와 데이터를 지키기 위해, 사용하기 전에 독커 컨테이너의 무결성(신뢰성, integrity)를 검증하기를 강하게 권장합니다.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

몇몇 도커 액션의 예시를 보려면, Docker-image.yml 워크플로우와 도커 컨테이너 액션 생성하기를 참고하세요.

자세한 내용은 [깃허브 액션](츨 고사헤요ㅣ)

더 많은 정보를 위해 워크플로우 문법을 참고하세요.

워크플로우 상태(status) 뱃지 레포지토리에 추가하기#

상태뱃지는 워크플로우가 현재 실패하고 있는지 통과했는지를 보여줍니다. 일반적으로 README.md파일에 스테이터스 뱃지를 추가합니다. 물론, 원하는 어떠한 웹페이지라도 추가할 수 있습니다. 디폴트로 뱃지는 디폴트 브랜치(주로 master)의 상태를 보여줍니다. 물론 특정 브랜치나, branch를 사용하고 있는 event나, URL의 event 쿼리 파라미터로도 보여줄 수 잇습니다.

만약 워크플로우가 name 키워드를 사용한다면 이름으로 참조할 수 있습니다. 만약 이름이 공백을 포함한다면, URL encoded 문자열인 %20으로 공백을 대체하여야 합니다."워크플로우 문법"을 참고하세요.

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

만약 name이 없을 경우, 레포지토리의 루트디렉토리의 상대경로로 사용하여 참조할 수 있습니다.

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_FILE_PATH>/badge.svg

워크플로우 `name`을 사용하는 경우 예시#

이 마크다운 예시에서는 Greet Everyone이라는 이름의 뱃지를 추가합니다. 이 레포지토리의 OWNER는 actoins 조직이며 REPOSITORY 이름은 hello-world입니다.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg)

파일 경로를 사용하는 경우#

이 마크다운 예시에서는 스테이터스 뱃지를 .github/workflows/main.yml의 경로와 함께 추가합니다. 레포지토리의 OWNER는 actions조직이며, REPOSITORY 이름은 hello-world입니다.

![](https://github.com/actions/hello-world/workflows/.github/workflows/main.yml/badge.svg)

`branch` 파라미터를 쓸 경우#

이 마크다운 예시에서는 feature-1이라는 브랜치에 대해 상태 뱃지를 추가합니다.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?branch=feature-1)

`event` 파라미터를 쓸 경우#

이 마크다운 예시에서는 pull_request 이벤트에 트리거되어 실행되는 워크플로우의 상태를 보여주는 뱃지를 추가합니다.

![](https://github.com/actions/hello-world/workflows/Greet%20Everyone/badge.svg?event=pull_request)

더 읽기#

생략합니다.