Cb-tumblebug: Automate opening a PR to update Swagger API doc by a workflow

[seokho-son]

• 컨트리뷰터는 소스코드에 API 관련 내용(struct, comment 등)을 수정한 경우, make swag 을 통해 API 문서를 자동 생성하고 있습니다. 그리고 컨트리뷰터가 PR을 열어서 해당 파일을 업데이트하고 있습니다. (https://github.com/cloud-barista/cb-tumblebug/wiki/API-Document-Update)

  • 예를 들어,
    
    
    
    • 컨트리뷰터가 API 관련 comment 수정하였다면, https://github.com/cloud-barista/cb-tumblebug/blob/dc8e9e40d207343ae0b2868901a2d7f11f7ae7b5/src/api/rest/server/mcir/image.go#L12
    
    
    • 컨트리뷰터는 'make swag' 을 수행해서 docs.go, swagger.json, swagger.yaml 파일을 생성할 것입니다. (https://github.com/cloud-barista/cb-tumblebug/tree/main/src/api/rest/docs),
    
    
    • 그리고, 컨트리뷰터는 docs.go, swagger.json, swagger.yaml 파일을 PR을 통해서 업데이트할 것입니다.
    
    
    • 예시: https://github.com/cloud-barista/cb-tumblebug/pull/760/files
    
    

• 현재 이 과정(make swag 또는 swag init)을 컨트리뷰터가 직접 수행하고 있는데, 다소 귀찮은 작업입니다. (API 수정에 대한 리뷰가 완료되었다면, 보통 자동 생성되는 문서에 대해서 따로 리뷰가 필요하지도 않습니다.)

• Workflow action을 추가하여 자동 처리되도록 만들 수 없을까요?
  
  
  
  • https://github.com/cloud-barista/cb-tumblebug/tree/main/.github/workflows
    
    
    
    
    
    • *.go 파일에 대한 수정 commit이 main branch에 merge된 경우,
    
    
    
    • background에서 자동으로 'make swag'을 수행하고
    
    
    
    • docs.go, swagger.json, swagger.yaml 파일 업데이트가 필요한 경우, 이를 커밋하여 PR을 오픈
    
    
    
  
  

도움 주실 분~?

[jihoon-seo]

[Pseudocode]

• Workflow 실행 조건 후보들:
  
  
  
  • src/core/*/*.go 파일 OR src/api/rest/server/*/*.go 파일에 변경이 발생한 경우
  
  
• 단계
  
  
  
  • Checkout CB-TB codes (using actions/checkout@v2)
  
  
  • (필요 시) go build를 위한 환경 구축
  
  
  • swag 설치 (go install ... 로 설치할 수도 있지만, 만약 go build를 위한 환경이 필요하지 않다면, swag 바이너리를 받아서 활용할 수도 있음)
  
  
  • src/ 에서 make swag 실행
  
  
  • Create Pull Request (참고)
  
  
  • docs.go, swagger.json, swagger.yaml 파일 업데이트가 필요한지 체크하고, 필요한 경우에만 PR을 열도록 할 수도 있음
  
  

[seokho-son]

@computerphilosopher
Github workflow 만들어보신 적 있으신가요? ^^ (예전에 test workflow 제안해주셨던 것이 생각났습니다.)
혹시 기여가 가능하실지 문의 드립니다. 편하게 응답 주세요

[computerphilosopher]

@seokho-son

github workflow는 해본적이 없지만 Travis CI는 회사에서 써본 경험이 있습니다.

기본 구조는 비슷할테니 한 번 시도해보겠습니다.

[seokho-son]

@computerphilosopher
감사합니다!! 👍

하시면서 어려운 부분이 있으면 알려주세요~! (참고로 작성한 workflow의 테스트는 1차적으로는 본인의 forked repository에서 돌려보시면 될 것 같습니다. 권한 이슈로 upstream에서 바로 구동시킬 수는 없을 거예요.)

@jihoon-seo 님~
혹시 @computerphilosopher 기여자께서 참고하실만한 reference가 있을까요? ^^
대략 기억나시는 것이 있으시면 공유해주세요~~

[seokho-son]

/assign @computerphilosopher

[seokho-son]

@hermitkim1 님~ 좋은 정보가 있으시면 여기 공유해주세요 ^^
(나중에 @computerphilosopher 께서 PR 오픈하시면, 리뷰도 부탁드려보겠습니다!! ㅎㅎ)

[jihoon-seo]

reference 등을 한번 작성해 보겠습니다 😊

---

• https://github.com/cloud-barista/cb-tumblebug/tree/main/.github/workflows
• https://github.com/cloud-barista/cb-larva/tree/main/.github/workflows
• https://github.com/cloud-barista/cb-operator/tree/master/.github/workflows

등을 참고하여..

[예시] (테스트 해 보지 않았습니다. 테스트가 필요합니다 😊)

name: Open Swagger-doc-updating PR

on: 
  push:
    branches:
      - main
    paths:
      - 'src/core/**/**.go'
      - 'src/api/rest/server/**/**.go'

jobs:
  # The job key is "update-swagger-doc"
  update-swagger-doc:
    # Job name is "Update Swagger doc"
    name: Update Swagger doc

    # This job runs on Ubuntu-latest
    runs-on: ubuntu-18.04
    strategy:
      matrix:
        go-version: [ '1.17' ]

    steps:
      - name: Set up Go ${{ matrix.go-version }}
        uses: actions/setup-go@v2
        with:
          go-version: ${{ matrix.go-version }}

      - name: Checkout source code
        uses: actions/[email protected]

      - name: Install swag
        run: |
          go install github.com/swaggo/swag/cmd/swag@latest

      - name: Update Swagger doc
        run: |
          cd src
          make swag

      - name: Create Pull Request
        id: create-pull-request
        uses: peter-evans/create-pull-request@v3
        with:
          token: ${{ secrets.UPDATE_SWAGGER_DOC_PAT }}
          commit-message: Update Swagger REST API doc
          committer: cb-bot <[email protected]>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          signoff: false
          branch: update-swagger-doc
          base: main
          delete-branch: true
          title: '[Workflow] Update Swagger REST API doc'
          body: |
            Update Swagger REST API doc
            - Updated with *today's* date
            - Auto-generated by [create-pull-request][1]
            [1]: https://github.com/peter-evans/create-pull-request
          labels: |
            swagger
            automated pr
          assignees: cloud-barista/cb-tumblebug-maintainer
          reviewers: cloud-barista/cb-tumblebug-maintainer
          team-reviewers: |
            owners
            maintainers
          draft: false

      - name: Check outputs
        run: |
          echo "Pull Request Number - ${{ steps.create-pull-request.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.create-pull-request.outputs.pull-request-url }}"

      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"

      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"

      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"

      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"

      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"

      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

[hermitkim1]

@computerphilosopher

Forked repository에서 workflow를 테스트 해보실때 필요한 몇가지 정보(제가 이전에 삽질 했던... ㅠ)를 공유 드립니다.

1. Actions 실행을 위한 권한 설정 - Managing GitHub Actions settings for a repository
2. Secret과 Personal Access Token (PAT)에 대한 간단 설명 - About GitHub secrets and personal access tokens

PAT 설정시 체크해야하는 항목이 있었던것 같은데요. 추후에 공유 드리겠습니다~

@computerphilosopher 감사합니다!! 👍

하시면서 어려운 부분이 있으면 알려주세요~! (참고로 작성한 workflow의 테스트는 1차적으로는 본인의 forked repository에서 돌려보시면 될 것 같습니다. 권한 이슈로 upstream에서 바로 구동시킬 수는 없을 거예요.)

@jihoon-seo 님~ 혹시 @computerphilosopher 기여자께서 참고하실만한 reference가 있을까요? ^^ 대략 기억나시는 것이 있으시면 공유해주세요~~

[computerphilosopher]

@jihoon-seo

현재 이슈 검토중입니다.

제시하신 파일에서는 make swag 명령어 적용 후 자동으로 Pull request를 여는 것으로 보이는데, 자동화된 변경사항이라 PR보다는 커밋을 바로 하는 편이 낫지 않을까요?

다음은 예시 action입니다.

https://github.com/marketplace/actions/git-auto-commit

https://github.com/marketplace/actions/add-commit

[seokho-son]

@computerphilosopher
이모지로 알람 확인을 못하셨을 수도 있으니.. ^^

저는 바로 업스트림에 커밋하는 것 보다는
PR이 오픈되면, 혹시라도 모를 문제(swagger api의 오류, 다른 PR들과 커밋 충돌 등등)를 검토할 수 있어서,

PR으로 여는 것을 선호합니다.. ^^
API 변경에 의해서 발생한 문제도 한 번 확인할 겸 말이죠.

하지만, 말씀하신 것과 같이, PR을 관리해야 하는 부담도 있긴 할 것 같습니다. 트레이드오프가 있네요.
@jihoon-seo @hermitkim1 께서도 동의하시는 듯하니 ~~

제안해주신 방법으로 기여를 해주시면 될 것 같습니다..!