Github Actions의 워크플로우를 작성할 때, on 속성의 값으로 워크플로우를 실행할 트리거가 될 이벤트를 정해줄 수 있다. 해당 이벤트 목록은 Actions Docs - events that trigger workflows에서 볼 수 있는데, 그 중 자주 사용되는 것을 몇가지 정리해보려 한다.

push

가장 자주 사용할 이벤트일 것이다. 커밋이나 태그를 푸쉬할 떄, 워크플로우를 실행시킨다. 참고로 Push이벤트는 개발자가 git push 명령어로 Push하는 것 뿐만 아니라, PR을 머지할 때 머지 커밋이 생기는 것도 포함한다.

on:
  push

위처럼 작성할 시, 모든 브렌치와 태그에 대해 push 이벤트가 발생하면 트리거된다.

Filter

특정 브렌치나 특정 태그에 대해서만 트리거되게 하고싶다면, 필터를 사용하면 된다. push 이벤트는 다음 6가지의 필터를 가지고 있다.

• branches
• branches-ignore
• tags
• tags-ignore
• paths
• paths-ignore

branches & branches-ignore

# flow1.yml
on:
  push:
    branches:
      - main
      - mona/octocat
      - releases/**
 
 # flow2.yml
 on:
   push:
    branches-ignore: 
      - dev
      - releases/**-alpha 

branches는 트리거에 포함할 브렌치를 결정한다. branches-ignore는 반대로 제외할 브렌치를 결정한다. 두 필터는 동시에 사용할 수는 없다.

main이나 mona/octocat, dev처럼 정확한 브렌치명을 적어줄 수 있다. 이 경우 정확히 같은 브렌치를 포함하거나 제외한다.

releases/**나 releases/**-alpha처럼 glob Pattern을 사용하여 여러 패턴에 대해 매칭해줄 수도 있다. 이 경우 해당 패턴에 매칭되는 브렌치를 포함하거나 제외한다.

on:
  push:
    branches:
      - releases/**
      - '!releases/**-alpha'

앞에서 branches와 branches-ignore를 동시에 쓸 수 없다고 했다. 하지만, 특정 Prefix를 가지는 브렌치를 포함하되 특정 몇몇 브렌치를 제외하고 싶을 수 있다. 이런 경우 !를 사용하면 된다. 위 예시에서는 releases/로 시작하는 브렌치를 포함하되, -alpha로 끝나는 브렌치들은 제외한다.

!를 사용할 때는, 반드시 !를 사용하지 않은 브렌치가 하나 이상 정의되어야 한다. 위 예시에서 - releases/** 구문을 제거할 경우, 에러가 발생한다.

tags & tags-ignore

# flow1.yml
on:
  push:
    tags:
      - releases-**
 
 # flow2.yml
 on:
   push:
    branches-ignore: 
      - test-**

tags는 트리거에 포함할 태그를 결정한다. tags-ignore는 반대로 제외할 태그를 결정한다. 두 필터는 동시에 사용할 수는 없다.

branches, branches-ignore와 마찬가지로 정확한 태그명을 적어주거나 glob 패턴을 사용할 수 있다. 마찬가지로 ! 구문도 사용할 수 있다.

on:
  push:
    branches:
      - main
      - mona/octocat
      - releases/**
    tags:
      - releases-**

위처럼 branches 계열의 필터와 같이 사용할 수도 있다.

paths & paths-ignore

# flow1.yml
on:
  push:
    paths:
      - '**.js'
 
 # flow2.yml
 on:
   push:
    paths-ignore: 
      - 'docs/**'

paths와 paths-ignore는 브렌치나 태그에 대해 동작하는 필터가 아니다. 해당 필터는 파일의 Path에 대해 동작하는 필터이다. 위처럼 paths를 **.js로 정의해주면, 프로젝트에 포함된 .js 파일이 변경될 경우 워크플로우가 실행된다. 이 역시, paths와 paths-ignore를 동시에 사용할 수 없으며, ! 구문을 사용할 수 있다.

paths 계열의 필터는 위 사진처럼 동작한다고 이해하면 된다. 그래서 branches나 tags 필터와 같이 사용할 경우, 둘 모두를 만족해야 트리거된다.

pull_request

Pull Request를 Open하거나 Reopen 혹은 PR의 Head Branch가 업데이트될 때 트리거된다. 다만, 해당 Pull Request에서 Merge Conflict가 발생할 경우 트리거되지 않는다. 이 경우 Merge Conflict를 해결하는 것이 우선되어야 한다.

on:
  pull_request

push일 때와 마찬가지로 아무 필터를 적용하지 않을 경우, 모든 pr에 대해 동작한다.

Filter

특정 브렌치에 대해서만 트리거되게 하고싶다면, 필터를 사용하면 된다. pull_request 이벤트는 다음 4가지의 필터를 가지고 있다.

• branches
• branches-ignore
• paths
• paths-ignore

PR은 태그랑은 무관하므로 tags와 tags-ignore 필터가 없다. 나머지 4개의 필터는 Push 이벤트의 것과 동일한 역할을 한다.

Activity Type

on:
  pull_request:
    types: [opened, reopened]

PR에는 여러 Activity Type들이 있다. 위에서 PR을 Open하거나 Reopen, Head Branch가 업데이트될 때 트리거된다고 했다. 이 opened, reopened, synchronize가 Activity Type인 것이며, 별도로 지정해주지 않을 경우 기본값으로 위 3가지를 트리거로 사용한다.

위 예시처럼 opened와 reopend만 지정할 경우, PR이 열릴 때와 닫힌 PR이 다시 열릴 때만 트리거된다. 더 많은 Activity Type들은 events that trigger workflow - pull_request에서 확인할 수 있다.

workflow_dispatch

워크플로우를 수동(manual)으로 실행할 수 있게 해주는 트리거이다. 해당 이벤트를 사용할 경우, Github Actions 페이지에서 워크플로우를 수동으로 실행할 수 있다. 또한, Github CLI나 Github API를 사용해서 실행할 수도 있다. 단, Github에 등록된 메인 브렌치에 해당 워크플로우 파일이 있어야 사용할 수 있다.

on: 
  workflow_dispatch

메인 브렌치에 위처럼 트리거 설정해주면...

이렇게 Actions 페이지에서 수동으로 워크플로우를 실행할 수 있다.

실행할 브렌치를 선택할 수도 있다.

inputs

workflow_dispatch는 inputs을 통해 사용자가 특정 값을 넣어줄 수 있다.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
        - info
        - warning
        - debug
      tags:
        description: 'Test scenario tags'
        required: false 
        type: boolean
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true 
      name:
        description: 'print name'
jobs:
  log-the-inputs:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Log level: $LEVEL"
          echo "Tags: $TAGS"
          echo "Environment: $ENVIRONMENT"
          echo "hello ${{ github.event.inputs.hello }}"
        env:
          LEVEL: ${{ github.event.inputs.logLevel }}
          TAGS: ${{ github.event.inputs.tags }}
          ENVIRONMENT: ${{ github.event.inputs.environment }}

위처럼 다양한 타입의 입력을 정의해줄 수 있다. 입력 값은 ${{ github.event.inputs.<<input_id>>로 가져올 수 있다.

위처럼 입력값을 넣을 수 있게 되었다.

입력값은 위처럼 워크플로우 내에서 사용할 수 있다.

TMI 하나만 넣자면, boolean 타입은 워크플로우 내부에서 boolean이 아닌 String으로 표현된다. 즉, false가 아닌 'false'이며, true가 아닌 'true'라는 문자열이다. 사용할 때 주의해서 사용하자.

workflow_run

다른 워크플로우의 실행과 연동되는 이벤트이다. 지정된 워크플로우가 실행 요청을 받거나 완료되면 실행된다.

# flow1.yml
name: Workflow Test
~~

# flow2.yml
name: Workflow Test2
on:
  workflow_run:
    workflows: [ Workflow Test ]

위의 경우 Workflow Test가 실행 요청을 받을 때와 실행이 완료됐을 때 Workflow Test2가 실행된다.

on:
  workflow_run:
    workflows: [ Workflow Test, Lint Test ]

위처럼 여러 개의 워크플로우를 지정해줄 경우, Workflow Test 혹은 Lint Test 워크플로우가 실행되면 트리거 된다.

# flow1.yml
name: flow1

# flow2.yml
name: flow2
on:
  workflow_run:
    workflows: [ flow1 ]

# flow3.yml
name: flow3
on:
  workflow_run:
    workflows: [ flow2 ]

위 예시처럼 여러 개의 워크플로우를 순차적으로 실행하게 할 수 있다. 다만, 이러한 Chain은 최대 3개까지 연결될 수 있다. 만약 A -> B -> C -> D -> E -> F라는 Chain이 있다면, B부터 F까지는 workflow_run을 사용했을 것이다. 이 경우 앞의 3개의 워크플로우 B, C, D까지만 실행되고, E와 F는 실행되지 않는다.

Filter

on:
  workflow_run:
    workflows: [Build]
    types: [requested]
    branches: [canary]

workflow_run에서도 Filter를 사용할 수 있다. branches와 branches-ignore 두가지를 사용할 수 있다.

Activity Type

Activity Type은 위에서 말했던 실행 요청을 받는 것(requested)과 정상 종료되는 것(completed) 두가지가 있다.

on:
  workflow_run:
    workflows: [ Workflow Test ]
    types:
      - completed

위처럼 types 속성으로 지정해줄 수 있다. 위 예시의 경우, Workflow Test가 실행 완료되면 트리거 된다.

참고로 requested 타입은 워크플로우가 re-run될 때는 트리거되지 않는다.

on:
  workflow_run:
    workflows: [Build]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - run: echo 'The triggering workflow passed'
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - run: echo 'The triggering workflow failed'

completed 타입은 정상 종료 뿐만 아니라 실패한 경우나 실행 취소한 경우도 모두 포함한다. 하지만 이전 워크플로우가 성공한 경우에만 실행하고 싶을 수 있다. 이 경우, github.event.workflow_run.conclusion 속성을 사용하면 된다.

위 예시에서는 jobs에서 if와 github.event.workflow_run.conclusion을 사용하여 이전 워크플로우의 종료 상태에 따라 실행 여부를 제어한다.

총총

위에서 정리한 4가지 이벤트 말고도 굉장히 많은 이벤트들이 존재한다. 하지만, 위 4가지만 알아도 우리가 필요로 하는 대부분의 경우에 적용할 수 있을 것이다.