며칠 전에 GitHub Actions에서 잡 요약(Job Summary) 기능이 추가되었다. YAML에 주석도 넣을 수 있지만 GitHub에서는 워크플로우 이름이 보이는데 워크플로우도 복잡해지면 종종 헷갈리기 때문에 워크플로우에 설명을 넣을 수 있으려나 해서 좀 살펴봤다. 물론 내가 생각했던 이런 기능은 아니었고 실행한 워크플로우의 요약을 정리해서 올릴 수 있는 기능이다.

GITHUB_STEP_SUMMARY를 이용한 잡 요약

사용법은 어렵지 않아서 문서에서 쉽게 파악할 수 있는데 워크플로우를 실행하면서 원하는 문자열을 GITHUB_STEP_SUMMARY 환경 파일에 저장하면 잡 요약이 출력되는 구조다.

jobs:
  somethin:
    runs-on: ubuntu-latest
    steps:
      - name: summary
        run: echo '### Hello world! :rocket:'' >> $GITHUB_STEP_SUMMARY

위에서 잡을 실행하는 스텝 중에서 echo '### Hello world! :rocket:'' >> $GITHUB_STEP_SUMMARY처럼 실행하면 잡 요약에 내용을 추가할 수 있다.

실행 결과를 보면 GITHUB_STEP_SUMMARY에 추가한 마크다운이 잘 표시된 것을 알 수 있다. 평소에는 실행 결과로 이 위치에 오류가 표시되곤 한다.

bash 리다이렉션

잡 요약을 만들기 위해 >>를 사용했는데 이는 bash 리다이렉션이다. >>와 >를 사용할 수 있는데 UNIX 기반 로컬 쉘에서도 똑같이 테스트해볼 수 있다.

$ echo "hello" >> sample.txt
$ echo "hello" >> sample.txt
$ cat sample.txt
hello
hello

>>를 사용하면 파일의 마지막에 내용을 계속 추가한다.

$ cat sample.txt
hello
hello
$ echo "world" > sample.txt
$ cat sample.txt
world

대신 >를 사용하면 파일의 기존 내용을 없애고 새로 추가한 내용으로 덮어쓴다.

추가적인 잡 요약 사용 방법

앞에서는 간단한 문자열을 출력했지만 여기서는 GitHub에서 사용할 수 있는 마크다운은 모두 사용할 수 있다. 좀 복잡한 마크다운을 출력해 보자.

jobs:
  something:
    runs-on: ubuntu-latest
    steps:
      - name: Generate list using Markdown
        run: |
          echo "# Title" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
          echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
          echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
          echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "## Subtitle" >> $GITHUB_STEP_SUMMARY
          echo "| Header | Header | Header | Header |" >> $GITHUB_STEP_SUMMARY
          echo "|--------|--------|--------|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Cell | Cell | Cell | Cell |" >> $GITHUB_STEP_SUMMARY
          echo "| Cell | Cell | Cell | Cell |" >> $GITHUB_STEP_SUMMARY
          echo "| Cell | Cell | Cell | Cell |" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- [ ] hi" >> $GITHUB_STEP_SUMMARY
          echo "- [ ] hi2" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`mermaid" >> $GITHUB_STEP_SUMMARY
          echo "stateDiagram-v2" >> $GITHUB_STEP_SUMMARY
          echo "    s1 --> s2" >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
      - run: echo hello world

이 워크플로우를 실행하면 다음과 같은 잡 요약이 출력된다.(수정 기능은 없기 때문에 체크리스트를 출력한 이후에 체크할 수는 없다.)

잡 요약 덮어쓰기

테스트를 위해 간단한 마크다운을 출력했지만 실 사용해서 실행 결과의 요약을 정리하려면 다양한 조건문이 들어가게 될 것이다. 이를 때 >를 사용하면 이미 GITHUB_STEP_SUMMARY에 작성한 요약을 덮어쓸 수 있다. 하지만 GITHUB_STEP_SUMMARY의 이름에서 알 수 있듯이 JOB_SUMMARY가 아니라 STEP_SUMMARY이므로 이는 step 단위로 동작한다.

jobs:
  something:
    runs-on: ubuntu-latest
    steps:
      - name: Generate list using Markdown
        run: |
          echo "# Title" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
          echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
          echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
          echo "Reset content" > $GITHUB_STEP_SUMMARY
      - run: echo hello world
      - name: summary
        run: echo "### Final Summary!" > $GITHUB_STEP_SUMMARY

그래서 위처럼 내용을 작성한 뒤에 "Reset content" > $GITHUB_STEP_SUMMARY로 내용을 오버라이드 하고 다음 스텝으로 넘어가서 다시 run: echo "### Final Summary!" > $GITHUB_STEP_SUMMARY로 덮어쓰려고 해도 아래처럼 두 스텝의 요약이 모두 저장된다.

스텝이 끝나면 요약 저장도 완료되기 때문에 다음 스텝에서 기존의 요약을 수정하거나 삭제할 수는 없다.

여러 잡의 요약

워크플로우를 쓰면 Job을 여러 개 작성하는 경우가 많이 있다.

jobs:
  something:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "# Title 1" >> $GITHUB_STEP_SUMMARY
  next:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "# Title 2" >> $GITHUB_STEP_SUMMARY

위처럼 여러 잡에서 요약을 모두 작성했을 때 아래처럼 각 요약을 한 번에 확인할 수 있다.

워크플로우에서 테스트 결과의 요약이나 커버리지 표시, 릴리스했을 때 릴리스한 버전 등 로그를 열어보지 않아도 확인하면 좋을 내용을 요약에 저장하면 좋을 것 같다.