Skip to main content
설명서에 자주 업데이트를 게시하며 이 페이지의 번역이 계속 진행 중일 수 있습니다. 최신 정보는 영어 설명서를 참조하세요.

실행기에서 GitHub CLI 사용

CI(연속 통합)를 위해 고급 GitHub Actions 기능을 사용하는 방법입니다.

참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.

예제 개요

이 문서에서는 예제 워크플로를 사용하여 GitHub Actions의 주요 CI 기능 중 일부를 보여 줍니다. 이 워크플로가 트리거되면 GitHub Docs 사이트에 끊어진 링크가 있는지 여부를 확인하는 스크립트가 자동으로 실행됩니다. 끊어진 링크가 있으면 워크플로는 GitHub CLI에서 세부 정보를 사용하여 GitHub 이슈를 만듭니다.

다음 다이어그램에서는 워크플로의 단계와 작업 내에서 실행되는 방법에 대한 개략적인 보기를 보여 줍니다.

GitHub CLI을(를) 사용하여 문제를 만드는 워크플로를 트리거하는 이벤트의 다이어그램

이 예제에서 사용되는 기능

예제 워크플로는 GitHub Actions의 다음 기능을 보여 줍니다.

기능구현
정기적으로 워크플로 실행schedule
토큰에 대한 권한 설정permissions
특정 조건이 충족되지 않는 한, 작업 실행 방지:if
워크플로에서 비밀 참조비밀
실행기에 리포지토리 복제actions/checkout
실행기에 node 설치:actions/setup-node
타사 작업 사용peter-evans/create-issue-from-file
실행기에서 스크립트 실행
사용 script/check-english-links.js출력 파일 생성
GitHub CLI을(를) 사용하여 기존 문제 확인gh issue list
GitHub CLI을(를) 사용하여 문제에 대한 주석 처리gh issue comment

예제 워크플로

다음 워크플로는 GitHub Docs Engineering 팀에서 만들었습니다. github/docs 리포지토리에서 이 파일의 최신 버전을 검토하려면 다음을 참조하세요. check-all-english-links.yml.

참고: 이 워크플로의 각 줄은 다음 섹션의 "예제 이해"에 설명되어 있습니다.

YAML
name: Check all English links

# **What it does**: This script once a day checks all English links and reports in issues.
# **Why we have it**: We want to know if any links break.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  schedule:
    - cron: '40 19 * * *' # once a day at 19:40 UTC / 11:40 PST

permissions:
  contents: read
  issues: write

jobs:
  check_all_english_links:
    name: Check all links
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}
      FIRST_RESPONDER_PROJECT: Docs content first responder
      REPORT_AUTHOR: docubot
      REPORT_LABEL: broken link report
      REPORT_REPOSITORY: github/docs-content
    steps:
      - name: Check out repo's default branch
        uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm
      - name: npm ci
        run: npm ci
      - name: npm run build
        run: npm run build
      - name: Run script
        run: |
          script/check-english-links.js > broken_links.md

      # check-english-links.js returns 0 if no links are broken, and 1 if any links
      # are broken. When an Actions step's exit code is 1, the action run's job status
      # is failure and the run ends. The following steps create an issue for the
      # broken link report only if any links are broken, so `if: ${{ failure() }}`
      # ensures the steps run despite the previous step's failure of the job.

      - if: ${{ failure() }}
        name: Get title for issue
        id: check
        run: echo "::set-output name=title::$(head -1 broken_links.md)"
      - if: ${{ failure() }}
        name: Create issue from file
        id: broken-link-report
        uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
        with:
          token: ${{ env.GITHUB_TOKEN }}

          title: ${{ steps.check.outputs.title }}
          content-filepath: ./broken_links.md
          repository: ${{ env.REPORT_REPOSITORY }}
          labels: ${{ env.REPORT_LABEL }}
      - if: ${{ failure() }}
        name: Close and/or comment on old issues
        env:
          NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}'
        run: |
          gh alias set list-reports "issue list \
                                       --repo ${{ env.REPORT_REPOSITORY }} \
                                       --author ${{ env.REPORT_AUTHOR }} \
                                       --label '${{ env.REPORT_LABEL }}'"

          # Link to the previous report from the new report that triggered this
          # workflow run.

          previous_report_url=$(gh list-reports \
                                  --state all \
                                  --limit 2 \
                                  --json url \
                                  --jq '.[].url' \
                                  | grep -v ${{ env.NEW_REPORT_URL }} | head -1)

          gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"

          # If an old report is open and assigned to someone, link to the newer
          # report without closing the old report.

          for issue_url in $(gh list-reports \
                                  --json assignees,url \
                                  --jq '.[] | select (.assignees != []) | .url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
            fi
          done

          # Link to the newer report from any older report that is still open,
          # then close the older report and remove it from the first responder's
          # project board.

          for issue_url in $(gh list-reports \
                                  --search 'no:assignee' \
                                  --json url \
                                  --jq '.[].url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
              gh issue close $issue_url
              gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}"
            fi
          done

예제 이해

다음 표에서는 GitHub Actions 워크플로를 만들 때 이러한 각 기능을 사용하는 방법을 설명합니다.

코드 설명
YAML
name: Check all English links

GitHub 리포지토리의 “작업” 탭에 표시되는 워크플로 이름입니다.

YAML
on:
  workflow_dispatch:
  schedule:
    - cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST

workflow_dispatchscheduled를 워크플로에 대한 트리거로 정의합니다.

  • workflow_dispatch를 사용하면 UI에서 이 워크플로를 수동으로 실행할 수 있습니다. 자세한 내용은 workflow_dispatch를 참조하세요.
  • schedule 이벤트를 사용하면 cron 구문을 사용하여 워크플로를 자동으로 트리거하는 정기적인 간격을 정의할 수 있습니다. 자세한 내용은 schedule를 참조하세요.
YAML
permissions:
  contents: read
  issues: write

GITHUB_TOKEN에 부여된 기본 사용 권한을 수정합니다. 워크플로의 요구 사항에 따라 달라집니다. 자세한 내용은 "작업에 권한 할당"을 참조하세요.

YAML
jobs:

워크플로 파일에서 실행되는 모든 작업을 함께 그룹화합니다.

YAML
  check_all_english_links:
    name: Check all links

jobs 키 내에 저장된 ID가 check_all_english_links이고 이름이 Check all links인 작업을 정의합니다.

YAML
if: github.repository == 'github/docs-internal'

리포지토리 이름이 docs-internal이고 github 조직 내에 있는 경우에만 check_all_english_links 작업이 실행됩니다. 그렇지 않으면 작업이 건너뛴 것으로 표시됩니다.

YAML
runs-on: ubuntu-latest

Ubuntu Linux 실행기에서 실행되도록 작업을 구성합니다. 즉, GitHub에서 호스트된 새 가상 머신에서 작업이 실행됩니다. 다른 실행기를 사용하는 구문 예제는 "GitHub Actions에 대한 워크플로 구문"을 참조하세요.

YAML
    env:
      GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}
      REPORT_AUTHOR: docubot
      REPORT_LABEL: broken link report
      REPORT_REPOSITORY: github/docs-content

사용자 지정 환경 변수를 만들고, 사용자 지정 비밀을 사용하도록 기본 제공 GITHUB_TOKEN 변수를 다시 정의합니다. 이러한 변수는 워크플로의 뒷부분에서 참조됩니다.

YAML
    steps:

check_all_english_links 작업의 일부로 실행될 모든 단계를 함께 그룹화합니다. 워크플로의 각 작업에는 고유한 steps 섹션이 있습니다.

YAML
      - name: Check out repo's default branch
        uses: actions/checkout@v3

uses 키워드는 작업에 actions/checkout으로 이름이 지정된 작업을 검색하도록 지시합니다. 이 작업은 리포지토리를 체크 아웃하고 실행기로 다운로드하여 코드에 대해 작업(예: 도구 테스트)을 실행할 수 있도록 합니다. 워크플로가 리포지토리의 코드에 대해 실행되거나 리포지토리에 정의된 작업을 사용할 때마다 체크 아웃 작업을 사용해야 합니다.

YAML
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 16.8.x
          cache: npm

이 단계에서는 actions/setup-node 작업을 사용하여 실행기에서 지정된 버전의 node 소프트웨어 패키지를 설치합니다. 그러면 npm 명령에 액세스할 수 있습니다.

YAML
      - name: Run the "npm ci" command
        run: npm ci
      - name: Run the "npm run build" command
        run: npm run build

run 키워드는 실행기에서 명령을 실행하도록 작업에 지시합니다. 이 경우 npm cinpm run build 명령은 별도의 단계로 실행되어 리포지토리에 Node.js 애플리케이션을 설치하고 빌드합니다.

YAML
      - name: Run script
        run: |
          script/check-english-links.js > broken_links.md

run 명령은 리포지토리의 script/check-english-links.js에 저장된 스크립트를 실행하고 출력을 broken_links.md 파일로 파이프합니다.

YAML
      - if: ${{ failure() }}
        name: Get title for issue
        id: check
        run: echo "::set-output name=title::$(head -1 broken_links.md)"

check-english-links.js 스크립트가 끊어진 링크를 검색하고 0이 아닌(살패) 종료 상태를 반환하는 경우 워크플로 명령을 사용하여 broken_links.md 파일의 첫 번째 줄 값이 있는 출력을 설정합니다(다음 단계에서 사용됨).

YAML
      - if: ${{ failure() }}
        name: Create issue from file
        id: broken-link-report
        uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
        with:
          token: ${{ env.GITHUB_TOKEN }}

          title: ${{ steps.check.outputs.title }}
          content-filepath: ./broken_links.md
          repository: ${{ env.REPORT_REPOSITORY }}
          labels: ${{ env.REPORT_LABEL }}

peter-evans/create-issue-from-file 작업을 사용하여 새 GitHub 이슈를 만듭니다. 이 예제는 b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e SHA를 사용하여 특정 버전의 작업에 고정됩니다.

YAML
      - if: ${{ failure() }}
        name: Close and/or comment on old issues
        env:
          NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}'
        run: |
          gh alias set list-reports "issue list \
                                       --repo ${{ env.REPORT_REPOSITORY }} \
                                       --author ${{ env.REPORT_AUTHOR }} \
                                       --label '${{ env.REPORT_LABEL }}'"
          previous_report_url=$(gh list-reports \
                                  --state all \
                                  --limit 2 \
                                  --json url \
                                  --jq '.[].url' \
                                  | grep -v ${{ env.NEW_REPORT_URL }} | head -1)

          gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"

gh issue list를 사용하여 이전 실행에서 이전에 만든 이슈를 찾습니다. 이후 단계에서 더 간단히 처리하기 위해 gh list-reports별칭이 지정됩니다. 이슈 URL을 가져오기 위해 jq 식은 결과 JSON 출력을 처리합니다.

gh issue comment는 이전 이슈에 연결되는 새 이슈에 주석을 추가하는 데 사용됩니다.

YAML
          for issue_url in $(gh list-reports \
                                  --json assignees,url \
                                  --jq '.[] | select (.assignees != []) | .url'); do
            if [ "$issue_url" != "$" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report]($)"
            fi
          done

이전 실행의 이슈가 열려 있고 다른 사람에게 할당된 경우 gh issue comment를 사용하여 새 이슈에 대한 링크가 있는 주석을 추가합니다.

YAML
          for issue_url in $(gh list-reports \
                                  --search 'no:assignee' \
                                  --json url \
                                  --jq '.[].url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
              gh issue close $issue_url
              gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}"
            fi
          done

이전 실행의 이슈가 열려 있고 다른 사용자에게 할당되지 않은 경우 다음을 수행합니다.

  • gh issue comment를 사용하여 새 이슈에 대한 링크가 있는 주석을 추가합니다.
  • gh issue close를 사용하여 이전 이슈를 닫습니다.
  • gh issue edit로 이전 이슈를 편집하여 특정 GitHub 프로젝트 보드에서 제거합니다.

다음 단계