Github Action:

Aiden Hong

@blod9

Workflow syntax with examples 

Workflow syntax with examples

Github action workflow는 반드시 YAML 문법을 사용하며 파일 역시 .yml 또는 .yaml 확장자를 가진다.

그리고 반드시 repository root의 .github/workflows 폴더에 위치하여야 한다.

Workflow syntax with examples

name

workflow의 이름을 설정한다. 여기에 설정된 이름은 Repository actions 페이지에 표시 되는 이름이다. 만약 이 부분을 생략한다면 workflow의 file path가 기본적으로 설정된다.

on

on은 필수적이다. workflow가 트리거 될 event의 이름들을 나열한다. 단일로도 작성 가능하고 배열과 유사하게 리스트로도 작성 가능하다.

Workflow syntax with examples

on

event 마다 세부적인 설정을 할 수 있다. 예를 들면 push, pull_request event는 타겟이 되는 특정 브랜치를 설정할 수 있다. event에 대한 세부적인 설정을 할 때는 event_name뒤에 :클론을 붙인다.

Workflow syntax with examples

on.<event_name>.types

이벤트 중에는 여러개의 타입으로 나뉘는 것들이 있는데, 예를 들면 release 이벤트는 create, edited, deleted 등의 type을 가진다. type지정은 types 키워드에 Array로 지정하여 사용할 수 있다.

Workflow syntax with examples

on.<push|pull_request>.<branches|tags>

push나 pull_request 이벤트를 사용할 때 target이 되는 branch나 tag를 설정할 수 있다. 설정하게 되면 해당 branch나 tag에서 이벤트가 발생했을 때만 트리거된다.

branchs나 tags에는 '*', '**', '?', '+'등을 이용해 이름에 패턴을 넣을 수 있다.

filter pattern에 대한 제세한 내용은 링크 참조

Workflow syntax with examples

on.<push|pull_request>.<branches-ignore|tags-ignore>

branches와  tags와는 반대로 특정 타겟만 제외하고 트리거 시키고 싶다면 -igonre를 사용한다.

Workflow syntax with examples

on.<push|pull_request>.<branches-ignore|tags-ignore>

한 이벤트에서 branches와 branches-ignore 그리고 tags와 tags-ignore를 동시에 사용하는 것은 안된다. 그리고 허용이 된다고 해도 무의미하다.  

예를 들어, branches로 main 브랜치를 지정했는데 branches-ignore에 dev 지정하는 건 의미가 없다.  

Workflow syntax with examples

on.<push|pull_request>.<paths|paths-ignore>

특정 파일이나 디렉토리가 변경되면 트리거 하거나 특정 파일이나 디렉토리만 변경되면 트리거를 안할 수 있다. branches와 tags와 마찬가지로 paths와 paths-ignore는 함께 사용할 수 없다.

왼쪽 예시는 push할 때 md파일만 변경 되었다면 트리거 되지않는다.

그리고 만약 md파일을 포함하여 다른 파일도 같이 수정 되었다면 트리거 된다.

Workflow syntax with examples

on.workflow_dispatch

workflow_dispatch는 수동적인 이벤트이다.  workflow가 workflow_dispatch 이벤트를 포함한다면 github repo - actions page - 해당 workflow에 workflow를 dispatch할 수 있는 버튼이 생성된다.

on.workflow_dispatch.inputs

버튼을 눌러 dispatch할 때 inputs을 사용하면 workflow에 필요한 인자를 함께 넘겨줄 수 있다.

Workflow syntax with examples

on.workflow_dispatch.inputs - example

Workflow syntax with examples

on.workflow_dispatch.inputs - example

Workflow syntax with examples

on.workflow_dispatch.inputs - example

- description

  input에 대한 설명

- required

  input의 필수 여부

- default

  input이 들어오지 않을 경우, 기본  값

Workflow syntax with examples

on.schedule

특정 시간에 주기적으로, 혹은 한 번만 workflow를 실행 하고 싶다면 schedule을 사용한다. 이 것을 사용할 때는 몇 가지 규칙이 있다.

1. 시간은 UTC 시간을 기준으로 한다.

2. 문법은 POSTIX cron 문법을 사용한다.

3. 예약된 workflow는 default or base 브랜치의 마지막 커밋이 기준이 되어 실행된다.

4. 스케줄링의 주기는 최소 5분 이상이어야 한다.

Workflow syntax with examples

on.schedule - example

5분마다 실행 되는 workflow

Workflow syntax with examples

env

- 워크플로우 모든 job에서 사용할 수 있는 환경 변수를 선언한다.

- env 속성은 job, step 단계에서 선언하여 지역 환경 변수를 만들어 사용할 수 있는데 동일한 이름의 환경 변수가 있을 경우 오버라이드가 된다.

Workflow syntax with examples

env - example

Workflow syntax with examples

defaults - example

Workflow syntax with examples

jobs

Jobs는 workflow를 이루는 1개 또는 여러개의 작업들을 작성한다. 기본적으로 병렬로 실행되지만 순차적으로 실행하고 싶다면 needs 라는 키워드를 이용하여 작업들의 종속성을 정의할 수 있다.

jobs.<job_id>

각 job은 반드시 job id를 작성하여 하며 이 id는 유니크 해야한다. 명명규칙은 다음과 같다.

- 시작은 문자나 '_'로 한다. 

- 영어, 숫자, '_' 로만 작성해야한다.

Workflow syntax with examples

runs-on은 필수적인 값이다.

job이 실행될 머신의 타입을 지정한다. github action은 머신 유형마다 레이블을 지정하여 제공한다. runs-on의 값으로 레이블을 넣으면 된다. 또한 github에서 제공하는 머신말고 self-hosted runner도 사용 가능하다.

예를 들어, 가상머신 Ubuntu 20.04 은 "ubuntu-latest" 레이블을 가진다.

jobs.<job_id>.runs-on

Workflow syntax with examples

jobs.<job_id>.runs-on - examples

Workflow syntax with examples

jobs.<job_id>.needs

needs 는 의존성을 가지는 다른 job을 명시하여 해당 job이 실행되기 전 완료되어야 하는 job을 단일 또는 리스트로 명시합니다. needs에 작성된 job이 실행 중 실패한 다면 해당 job은 skip됩니다.

Workflow syntax with examples

jobs.<job_id>.outputs

outputs는 해당 job의 의존 되는 job에게 사용할 출력을 작성한다. output은 문자열 또는 runner에서 사용하는 context를 job expression으로 작성하여 평가된 문자열만 작성된다.

Workflow syntax with examples

jobs.<job_id>.outputs - example

옆 예제는

1. job2가 job1에 의존 된다.

2.  job1의 outputs은 output1과 oput2를 가진다.

3. job2에서 needs cotext를 통해 job1의 outputs에 접근한다.

Workflow syntax with examples

jobs.<job_id>.needs - example

예제 같은 경우, job2는 job1가 완료 되어야 실행된다.

job3은 job1, job2가 모두 완료 되어야 실행된다.

따라서 job1, job2, job3가 순차적으로 실행되게 된다.

Workflow syntax with examples

jobs.<job_id>.if

if 키워드는 context나 expression을 이용하여 조건을 제시하고 조건을 충족하지 않을 경우, job을 실행하지 않도록 한다.  

Workflow syntax with examples

jobs.<job_id>.if - example

job1은 if의 조건식이 true로 충족하여 job1이 실행되었고 job2는 조건식의 값이 false라 skip 된 것을 확인할 수 있다.

Workflow syntax with examples

jobs.<job_id>.steps

steps는 job의 task 집합이다. 하나의 job 안에 step들은 순차적으로 실행된다. steps는 command를 실행할 수도 있고 docker image를 만들 수도 있고 레지스트리에 publish도 가능하며 action을 실행할 수도 있다.

id, name, if, env 키워드는 job.<id | name| if | env> 키워드와 사용법이 동일하다.  step.env는 이미 job에 같은 이름의 변수가 선언되어 있다면 오버라이드한다.

Workflow syntax with examples

jobs.<job_id>.steps[*].uses

uses 키워드는 step의 단위를 재사용 가능하도록 만든 action을 사용한다.
 action은 같은 레포지토리 안에 만들어진  action이나 public한 action, 또는 published docker image를 사용할 수 있다.

action에 따라 inputs를 요구하는데 이것은 with 키워드를 통해 전달할 수 있다.

Workflow syntax with examples

jobs.<job_id>.steps[*].uses - example

hello-world-docker-action은  github action에서 제공하는 who-to-greet라는 input에 이름을 넣으면 인사를 콘솔에 출력해 주는 action이다.

Workflow syntax with examples

jobs.<job_id>.steps[*].run

run은 OS shell에서  command line을 실행 해주는 키워드 이다. 만약 step의 name 키워드를 작성하지 않으면 run에서 출력된 text가 default name이 된다.

run 에 command line이 실행 되는 것을 확인 할 수 있다. 그리고 name을 작성하지 않은 두 번째 step은 name 이 run에 작성한 command line이 된 걸 볼 수 있다.

Workflow syntax with examples

jobs.<job_id>.steps[*].with

with 키워드는 action에서 선언한 inputs의 값을 전달할 때 사용하는 키워드이다.

jobs.<job_id>.steps[*].with.entrypoint

jobs.<job_id>.steps[*].with.args