Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automate opening a PR to update Swagger API doc by a workflow #804

Closed
seokho-son opened this issue Sep 28, 2021 · 10 comments · Fixed by #894
Closed

Automate opening a PR to update Swagger API doc by a workflow #804

seokho-son opened this issue Sep 28, 2021 · 10 comments · Fixed by #894
Assignees
Labels
feature request Issue related with new feature

Comments

@seokho-son
Copy link
Member

seokho-son commented Sep 28, 2021

도움 주실 분~?

@seokho-son seokho-son added the question Further information is requested label Sep 28, 2021
@jihoon-seo
Copy link
Member

[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
Copy link
Member Author

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

@computerphilosopher
Copy link
Member

computerphilosopher commented Sep 29, 2021

@seokho-son

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

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

@seokho-son
Copy link
Member Author

@computerphilosopher
감사합니다!! 👍

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

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

@seokho-son
Copy link
Member Author

/assign @computerphilosopher

@seokho-son seokho-son added feature request Issue related with new feature and removed question Further information is requested labels Sep 29, 2021
@seokho-son seokho-son changed the title Can we automate opening a PR to update Swagger API doc Automate opening a PR to update Swagger API doc by a workflow Sep 29, 2021
@seokho-son
Copy link
Member Author

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

@jihoon-seo
Copy link
Member

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


등을 참고하여..

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

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/checkout@v2.3.4

      - 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 <noreply@github.com>
          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"

@yunkon-kim
Copy link
Member

@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
Copy link
Member

computerphilosopher commented Oct 19, 2021

@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
Copy link
Member Author

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

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

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

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

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

computerphilosopher added a commit to computerphilosopher/cb-tumblebug that referenced this issue Oct 26, 2021
@jihoon-seo jihoon-seo linked a pull request Oct 27, 2021 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature request Issue related with new feature
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants