사용자 지정 트랜스포머로 GitHub Actions Importer 확장하기

GitHub Actions Importer는 내장 매핑을 확장할 수 있는 기능을 제공해요. 마이그레이션할 때 자동 변환이 안 되는 항목을 직접 정의하고 싶다면 이 기능을 쓰면 돼요.

출처: 문서

본문

GitHub Actions Importer는 내장 매핑을 확장할 수 있는 기능을 제공합니다.

사용자 지정 트랜스포머에 대해

GitHub Actions Importer는 사용자 지정 트랜스포머(custom transformer)를 만들어 내장 매핑을 확장할 수 있는 기능을 제공합니다. 사용자 지정 트랜스포머는 다음과 같은 용도로 사용할 수 있습니다:

GitHub Actions Importer가 자동으로 변환하지 않는 항목을 변환하거나, 항목이 변환되는 방식을 수정합니다. 자세한 내용은 Creating custom transformers for items를 참고하세요.
러너에 대한 참조를 변환해서 다른 러너 라벨을 사용하게 합니다. 자세한 내용은 Creating custom transformers for runners를 참고하세요.
기존 파이프라인의 환경 변수 값을 GitHub Actions 워크플로로 변환합니다. 자세한 내용은 Creating custom transformers for environment variables를 참고하세요.

GitHub Actions Importer와 함께 사용자 지정 트랜스포머 사용하기

사용자 지정 트랜스포머에는 GitHub Actions Importer가 플러그인, 작업(task), 러너 라벨, 환경 변수를 GitHub Actions에서 작동하도록 변환하는 데 사용할 수 있는 매핑 로직이 들어 있습니다. 사용자 지정 트랜스포머는 Ruby를 기반으로 구축된 도메인 특화 언어(DSL)로 작성되며, .rb 파일 확장자를 가진 파일 안에 정의됩니다.

audit, dry-run, migrate 명령과 함께 사용할 사용자 지정 트랜스포머 파일을 지정하려면 --custom-transformers CLI 옵션을 사용할 수 있습니다.

예를 들어 사용자 지정 트랜스포머가 transformers.rb라는 파일에 정의되어 있다면 다음 명령을 사용해서 GitHub Actions Importer와 함께 사용할 수 있습니다:

gh actions-importer ... --custom-transformers transformers.rb

또는 glob 패턴 구문을 사용해서 여러 사용자 지정 트랜스포머 파일을 지정할 수 있습니다. 예를 들어 여러 사용자 지정 트랜스포머 파일이 transformers라는 디렉터리 안에 있다면 다음 명령으로 모두 GitHub Actions Importer에 제공할 수 있습니다:

gh actions-importer ... --custom-transformers transformers/*.rb

[!NOTE] 사용자 지정 트랜스포머를 사용할 때 트랜스포머 파일은 gh actions-importer 명령이 실행되는 디렉터리, 또는 그 하위 디렉터리에 있어야 합니다.

항목용 사용자 지정 트랜스포머 만들기

기존 빌드 스텝이나 트리거를 GitHub Actions의 해당 항목으로 변환할 때 GitHub Actions Importer가 사용할 사용자 지정 트랜스포머를 만들 수 있습니다. 이 기능은 특히 다음과 같은 경우에 유용합니다:

GitHub Actions Importer가 항목을 자동으로 변환하지 않을 때.
GitHub Actions Importer가 항목을 변환하는 방식을 바꾸고 싶을 때.
기존 파이프라인이 Jenkins의 공유 라이브러리 같은 사용자 지정 또는 독점 확장을 사용하고, 이 스텝들이 GitHub Actions에서 어떻게 작동해야 하는지 정의해야 할 때.

GitHub Actions Importer는 Ruby를 기반으로 구축된 DSL로 정의된 사용자 지정 트랜스포머를 사용합니다. 빌드 스텝과 트리거용 사용자 지정 트랜스포머를 만들려면:

각 사용자 지정 트랜스포머 파일에는 최소 하나의 transform 메서드가 포함되어야 합니다.
각 transform 메서드는 Hash, Hash의 배열, 또는 nil을 반환해야 합니다. 이 반환값은 YAML로 정의된 액션에 해당합니다. 액션에 대한 자세한 내용은 Understanding GitHub Actions를 참고하세요.

빌드 스텝용 사용자 지정 트랜스포머 예시

다음 예시는 "buildJavaScriptApp" 식별자를 사용하는 빌드 스텝을 다양한 npm 명령을 실행하도록 변환합니다:

transform "buildJavaScriptApp" do |item|
  command = ["build", "package", "deploy"].map do |script|
    "npm run #{script}"
  end

  {
    name: "build javascript app",
    run: command.join("\n")
  }
end

위 예시는 다음 GitHub Actions 워크플로 스텝을 생성합니다. buildJavaScriptApp 식별자를 가진 변환된 빌드 스텝들로 구성됩니다:

- name: build javascript app
  run: |
    npm run build
    npm run package
    npm run deploy

transform 메서드는 인자에서 소스 CI/CD 인스턴스의 빌드 스텝 식별자를 사용합니다. 이 예시에서 식별자는 buildJavaScriptLibrary입니다. 쉼표로 구분된 값을 사용해서 transform 메서드에 여러 식별자를 전달할 수도 있습니다. 예를 들어 transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }.

[!NOTE] item의 데이터 구조는 CI/CD 플랫폼과 변환되는 항목의 유형에 따라 다릅니다.

러너용 사용자 지정 트랜스포머 만들기

소스 CI/CD 인스턴스의 러너와 해당하는 GitHub Actions 러너 사이의 매핑을 사용자 지정할 수 있습니다.

GitHub Actions Importer는 Ruby를 기반으로 구축된 DSL로 정의된 사용자 지정 트랜스포머를 사용합니다. 러너용 사용자 지정 트랜스포머를 만들려면:

사용자 지정 트랜스포머 파일에는 최소 하나의 runner 메서드가 있어야 합니다.
runner 메서드는 두 개의 파라미터를 받습니다. 첫 번째 파라미터는 소스 CI/CD 인스턴스의 러너 라벨이고, 두 번째 파라미터는 해당하는 GitHub Actions 러너 라벨입니다. GitHub Actions 러너에 대한 자세한 내용은 GitHub-hosted runners reference를 참고하세요.

러너용 사용자 지정 트랜스포머 예시

다음 예시는 하나의 러너 라벨을 결과 워크플로의 하나의 GitHub Actions 러너 라벨로 변환하는 runner 메서드를 보여줍니다.

runner "linux", "ubuntu-latest"

runner 메서드를 사용해서 하나의 러너 라벨을 결과 워크플로의 여러 GitHub Actions 러너 라벨로 변환할 수도 있습니다.

runner "big-agent", ["self-hosted", "xl", "linux"]

GitHub Actions Importer는 러너 라벨을 최대한 잘 매핑하려고 시도합니다. 이 작업을 수행할 수 없는 경우 ubuntu-latest 러너 라벨이 기본값으로 사용됩니다. runner 메서드와 함께 특수 키워드를 사용해서 이 기본값을 제어할 수 있습니다. 예를 들어 다음 사용자 지정 트랜스포머는 기본 러너로 ubuntu-latest 대신 macos-latest를 사용하도록 GitHub Actions Importer에 지시합니다.

runner :default, "macos-latest"

환경 변수용 사용자 지정 트랜스포머 만들기

소스 CI/CD 파이프라인의 환경 변수와 GitHub Actions에서의 값 사이의 매핑을 사용자 지정할 수 있습니다.

GitHub Actions Importer는 Ruby를 기반으로 구축된 DSL로 정의된 사용자 지정 트랜스포머를 사용합니다. 환경 변수용 사용자 지정 트랜스포머를 만들려면:

사용자 지정 트랜스포머 파일에는 최소 하나의 env 메서드가 있어야 합니다.
env 메서드는 두 개의 파라미터를 받습니다. 첫 번째 파라미터는 원래 파이프라인의 환경 변수 이름이고, 두 번째 파라미터는 GitHub Actions용 환경 변수의 업데이트된 값입니다. GitHub Actions 환경 변수에 대한 자세한 내용은 Store information in variables를 참고하세요.

환경 변수용 사용자 지정 트랜스포머 예시

사용자 지정 트랜스포머를 설정해서 환경 변수를 매핑하는 방법은 여러 가지가 있습니다.

다음 예시는 파이프라인을 변환할 때 OCTO라는 이름의 기존 환경 변수의 값을 CAT로 설정합니다.
```
env "OCTO", "CAT"
```
특정 환경 변수의 모든 인스턴스를 제거해서 GitHub Actions 워크플로로 변환되지 않게 할 수도 있습니다. 다음 예시는 MONA_LISA라는 이름의 모든 환경 변수를 제거합니다.
```
env "MONA_LISA", nil
```
기존 환경 변수를 시크릿으로 매핑할 수도 있습니다. 예를 들어 다음 env 메서드는 MONALISA라는 이름의 환경 변수를 OCTOCAT이라는 이름의 시크릿으로 매핑합니다.
```
env "MONALISA", secret("OCTOCAT")
```
이렇게 하면 변환된 워크플로에 OCTOCAT이라는 이름의 시크릿에 대한 참조가 설정됩니다. 시크릿이 작동하려면 GitHub 저장소에 시크릿을 만들어야 합니다. 자세한 내용은 Using secrets in GitHub Actions를 참고하세요.
정규 표현식을 사용해서 여러 환경 변수의 값을 한 번에 업데이트할 수도 있습니다. 예를 들어 다음 사용자 지정 트랜스포머는 변환된 워크플로에서 모든 환경 변수를 제거합니다:
```
env /.*/, nil
```
다음 예시는 정규 표현식 매치 그룹을 사용해서 환경 변수 값을 동적으로 생성된 시크릿으로 변환합니다.
```
env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
```
[!NOTE] 정규 표현식을 사용할 때 env 메서드가 정의되는 순서가 중요합니다. 환경 변수 이름과 일치하는 첫 번째 env 트랜스포머가 이후의 env 메서드보다 우선합니다. 가장 구체적인 환경 변수 트랜스포머를 먼저 정의해야 합니다.

법적 고지

일부 내용은 MIT 라이선스에 따라 https://github.com/github/gh-actions-importer/에서 각색되었습니다:

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

사용자 지정 트랜스포머로 GitHub Actions Importer 확장하기