[FOSSLight / DevOps] VS Code extension 배포 자동화

현재 Fosslight scanner 오픈소스 컨트리뷰션을 하고있다. 이번에 DevOps 팀으로 가게 되었고, vs code extension 배포 자동화 issue를 맡아서 진행했다. vscode도 오랫만이라 어색했고, extension 배포는 안해봤지만, github action을 활용한 배포는 여러번 경험해봐서 어렵지 않게 pr 올릴 수 있었다. 현재는 pr review 중이고, 큰 문제가 없는 한 merge 될 것 같다. (두근두근)

나의 PR: https://github.com/fosslight/fosslight_scanner_vscode/pull/3

Publish vscode extension to Visual Studio Marketplace by persi0815 · Pull Request #3 · fosslight/fosslight_scanner_vscode

Description When a tag is created and a release is published, the GitHub Action is triggered. The action extracts the tag (version), updates the version field in the package.json, and then publishe...

github.com

추가)

해당 이슈 관련된 자료들이 있긴 했는데, 흩어져있어서 다른 분들은 보다 쉽게 개발하실 수 있도록 전체 과정을 포스팅 해보려 한다.

우선 이슈를 다시 한번 말해보자면, fosslight scanner extension을 release(발행)시에 vscode marketplace에 자동으로 버전 갱신과 함께 배포해야 했다. 발행 시에 태그를 생성하는데, 아래 사진 좌측에 v0.0.19라고 나와있는걸 태그라고 한다. 태그는 일반적으로 릴리즈 버전을 뜻하는데, 태그를 통해 릴리즈를 식별, 관리할 수 있다. 태그의 버전에 맞는 extension을 배포하면 되었다.

현재 marketplace로 가보면 이렇게 LG가 기존에 배포해놓은 extension과 나(persi)가 테스트용으로 배포한 extension을 확인할 수 있다. (테스트용은 merge 이후 곧바로 삭제할 예정)

그러면 이제 배포 과정을 알아보도록 하자.

1. 발행이 되면, 이를 트리거 삼아 github action이 실행

기존의 레포에서는 github action을 사용하지 않았어서 아예 새로 .github/workflows 디렉토리 부터 만들어주었다.

github action은 CI/CD의 파이프 라인으로 보통 특정 이벤트를 감지하면 실행이 된다. CI(Continuous Integration)를 통해 자동으로 빌드와 테스트가 실행이 되어 코드에 문제가 없는지 빠르게 확인할 수 있고, CD(Continuous Delivery/Deployment)을 통해 실제 운영환경에 자동으로 배포되도록 한다.

python 프로젝트의 github action workflow에서 트리거는 on: 을 통해 명시할 수 있다. 나는 발행이 되면 트리거 되도록 다음과 같이 설정했다.

on: 
  release:
    types: [published]

2. 태그에서 버전을 추출하여 extension 배포와 직접적으로 관련이 되는 package.json의 version 필드를 갱신

1) 태그 추출

- name: Extract version from tag
  id: extract_version
  run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV

2) package.json의 version 필드 갱신

- name: Update package version
  working-directory: ./fosslight-scanner
  run: npm version ${{ env.VERSION }} --no-git-tag-version

3. main으로 브랜치 이동 후 갱신한 version 필드 commit, push

브랜치를 main으로 이동 후 commit을 해야 제대로 commit이 된다. 그리고, commit은 github-action[bot]이 한 것으로 뜨게 했다.

1) 브랜치 이동

- name: Checkout main branch
  run: git checkout main

2) 갱신한 값 commit, push

- name: Commit version change
  run: |
    git config --local user.name "github-actions[bot]"
    git config --local user.email "github-actions[bot]@users.noreply.github.com"
    git add ./fosslight-scanner/package.json
    git commit -m "Update version to ${{ env.VERSION }}"

- name: Push changes
  run: git push origin HEAD:main

이렇게 gitbot이 commit한 걸로 뜬다 ㅎㅎ

4. VSCE (Visual Studio Code Extensions CLI) 통해 VS Code extension 배포

VS Code 확장 프로그램을 배포하는 여러가지 방법이 있는데, 그중 배포 과정이 간단하여 CI/CD 통합에 용이하고, 여러 플랫폼을 지원하며, 버전 관리가 간편하면서도 패키징 및 배포 전 유효성 검사를 지원해주는 장점을 지원해주는 vsce를 택했다.

* 이전에 태그명에 따라 package.json의 version 정보를 수정했는데, vsce는 해당 버전이 변경될때마다 이를 기반으로 패키징을 자동으로 수행해준다!!

1) VSCE 설치

- name: Install vsce
  working-directory: ./fosslight-scanner
  run: npm install -g vsce

디렉토리는 package.json이 있는 ./fosslight-scanner로 이동한 뒤 vsce를 설치해야 오류가 안생겨서 ./fosslight-scanner로 이동하게끔 했다.

2) VS Code extension 배포

- name: Publish VS Code Extension
  working-directory: ./fosslight-scanner
  env:
    VSCE_PAT: ${{ secrets.VSCE_TOKEN }}
  run: |
    vsce package
    vsce publish

vsce package 명령어는 확장을 하나의 .vsix 파일로 묶어준다.

vsce publish 명령어는 marketplace에 extension을 배포한다.

< 전체 yml >

name: Release vscode extension

on: 
  release:
    types: [published]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Checkout main branch
      run: git checkout main

    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '20'

    - name: Install dependencies
      working-directory: ./fosslight-scanner
      run: npm install

    - name: Extract version from tag
      id: extract_version
      run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
      
    - name: Update package version
      working-directory: ./fosslight-scanner
      run: npm version ${{ env.VERSION }} --no-git-tag-version

    - name: Commit version change
      run: |
        git config --local user.name "github-actions[bot]"
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
        git add ./fosslight-scanner/package.json
        git commit -m "Update version to ${{ env.VERSION }}"

    - name: Push changes
      run: git push origin HEAD:main
      
    - name: Install vsce
      working-directory: ./fosslight-scanner
      run: npm install -g vsce

    - name: Publish VS Code Extension
      working-directory: ./fosslight-scanner
      env:
        VSCE_PAT: ${{ secrets.VSCE_TOKEN }}
      run: |
        vsce package
        vsce publish

5. VSCE Token (PAT) 발급 & github secret에 넣기

윗 코드를 보면, vsce를 통해 marketplace에 배포할 때 VSCE_TOKEN을 사용하고 있음을 알 수 있다. 해당 토큰은 Personal Access Token이라는 인증정보로, extension을 게시할 때 publisher당 최소 하나가 필요하다. 나의 경우에는 github secret을 사용했다.

publisher를 생성하고, token을 발급받아서 publisher와 연결하는 과정은 다음과 같다.

1) AZUER DEVOPS에 회원가입

2) AZURE DEVOPS - Organization 생성

3) AZURE DEVOPS - 토큰 발급

이렇게 나온 토큰은 다시 열람할 수 없으니 꼭!! 복사해놓으시길 바랍니다.

4) MARKETPLACE - 회원가입 & publisher 생성

5) publisher와 토큰 연결

6) github secret에 pat 넣기

5. 테스팅 위해 package.json 수정하기

해당 레포의 경우에는 이미 extension을 배포해본 적이 있어서 package.json 기본설정은 되어있었다. 그런데, 이제 위에서 발급한 나의 토큰을 이용하여 배포를 해야 해서 name, displayName, publisher 필드를 바꿔주었다. 주의할 점은 publisher는 위에서 내가 설정한 publisher 이름으로 설정해야하고, displayName은 상관없지만, name 같은 경우에는 공백이 있으면 안되어서 '-'를 이용해주었다.

*만일 아예 extension 배포가 처음이라면 맨 아래쪽 내용을 참고하면 좋을 것 같다!

{
  "name": "fosslight-scanner-new-testing",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/fosslight/fosslight_vscode_extension.git"
  },
  "homepage": "https://fosslight.org",
  "displayName": "FOSSLight Scanner new testing",
  "publisher": "persi",
  "description": "A VSCode Extension made for the convenient use of FOSSLight Scanner",
  "icon": "foss_logo.png",
  "version": "0.0.4",
  "engines": {
    "vscode": "^1.90.0"
  },

기존에 배포된 확장을 업데이트 하고자 한다면, (새로 발행하여) package.json의 version 필드만 갱신면 된다. 그러면 새로 발행한 extension이 배포가 된다. 즉, 기존에 배포된 extension에서 버전이 증가하는 것이다.

6. 레포에서 merge, 발행(publish; release)

1) 작성한 코드 merge

git add . 
git commit -s -m “vscode extension release testing”
git push origin main

2) 발행(publish)

자신의 레포 url 뒤에 /release 입력해서 release 화면으로 가기

ex) https://github.com/persi0815/fosslight_scanner_vscode/releases

위에 사진에 있는 Draft a new release 버튼 누르고 버전과 타이틀 설정 후 발행(release)하기

태그는 아무거나 새로 만들면 되는데, 숫자는 아무거나 상관없지만 형태가 무조건 v0.0.0 이 되도록 해주자.

publish release 버튼 누르면 github action이 실행이 된다.

7. 잘 배포되었는지 확인

1) 버전 잘 갱신되었는지 package.json에서 커밋되고 푸시된 내용 확인

2) 조금만(내 경험상 짧으면 1초. 길면 30분? 실제로는 3시간이 걸리기도 한다고 함) 기다리고, marketplace에 가서 내가 발행할 때 작성한 버전명에 맞는 extention이 배포된 것 확인

https://marketplace.visualstudio.com/

이렇게 내가 배포한 것들만 따로 확인 할 수도 있다!

아예 extension 배포가 처음이라면?

1. Node.js, Vsce 설치

npm install -g vsce
혹은
npm install -g @vscode/vsce

2. 프로젝트 형태 초기화

vsce init

을 실행하면 아래 파일들이 생성된다.

- package.json : 확장 프로그램의 메타데이터 및 의존성을 정의하는 파일.

- src/extension.ts : 확장의 메인 로직을 담고 있는 TypeScript 파일 : 확장 개발에 대한 간단한 가이드.

- vsc-extension-quickstart.md : 확장 개발에 대한 간단한 가이드.

- README.md : 확장 프로그램에 대한 설명을 작성하는 파일.

- CHANGLOG.md : 확장의 변경 사항을 기록하는 파일.

3. 확장 프로그램의 기능 정의

src/extension.ts 파일을 수정하여 기능을 정의해주자.

막막하다면, fosslight_scanner_vscode 레포를 참고해도 좋을 것 같다!

4. package.json 파일 설정

확장 프로그램의 기능을 설정해주자.

도움받은 출처

https://pg-vscode-extn-kr.github.io/api/working-with-extensions/publishing-extension/

Publishing Extension

VS Code 익스텐션 API 한글 번역

pg-vscode-extn-kr.github.io

https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows

Use personal access tokens - Azure DevOps

Learn how to create and manage personal access tokens (PATs) as alternate passwords to authenticate to Azure DevOps.

learn.microsoft.com

Persi's code life