사용자 지정 GitHub 작업 게시

  • 6분

이제 작업에 적합한 표시 선택, 작업 문서화 및 버전 관리의 모범 사례, GitHub Marketplace에 작업을 게시하는 방법에 관해 알아봅니다.

작업 위치 선택

작업에 대한 두 가지 표시 옵션(퍼블릭 또는 프라이빗)을 나타내는 다이어그램.

작업을 만들 때는 먼저 해당 작업을 수행할 위치와 작업의 표시 여부(public 또는 private)를 결정하는 것이 중요합니다. 작업의 표시 여부는 해당 작업을 해제하는 데 필요한 권장 사항과 요구 사항을 결정합니다. 이 두 가지 표시 옵션에 대해 자세히 살펴보겠습니다.

공용

모든 리포지토리의 워크플로는 공용 작업을 사용할 수 있습니다. 오픈 소스로 만들거나 GitHub Marketplace를 통해 공개적으로 사용할 수 있게 할 목적으로 작업을 개발하려면, 다른 애플리케이션 코드와 묶는 대신 고유한 자체 리포지토리를 사용하는 것이 좋습니다(대부분의 경우에는 자체 리포지토리를 사용해야 합니다). 이렇게 하면 다른 소프트웨어처럼 작업을 버전 관리, 추적, 해제할 수 있습니다. 이렇게 하면 GitHub 커뮤니티가 작업을 쉽게 발견할 수 있고 문제를 수정하고 작업을 확장하는 개발자들의 코드베이스 범위를 좁힐 수 있으며 작업의 버전 관리를 다른 애플리케이션 코드의 버전 관리와 분리할 수 있습니다.

Private

작업이 프라이빗 리포지토리에 있는 경우, 동일한 리포지토리의 워크플로에서만 작업을 사용할 수 있습니다. 프라이빗 작업을 사용하면 작업 파일을 리포지토리의 모든 위치에 저장할 수 있습니다. 작업, 워크플로, 애플리케이션 코드를 단일 리포지토리에 결합하려면 작업을 .github 디렉터리에 저장하는 것이 좋습니다. 예를 들어 .github/actions/action-a 및 .github/actions/action-b를 지정합니다.

작업 문서화

설명서가 모호하거나 누락되었을 때 새로운 도구나 애플리케이션을 사용하는 것은 매우 번거로울 수 있습니다. 퍼블릭 또는 프라이빗 여부와 관계없이, 작업이 어떻게 작동하는지를 다른 사용자가 볼 수 있도록 유용한 설명서를 작업에 포함해야 합니다. 가장 먼저 할 일은 작업에 적합한 README.md 파일을 만드는 것입니다.

README.md 파일은 일반적으로 개발자가 작업의 작동 방식을 확인하는 첫 번째 단계입니다. 작업에 대한 모든 중요한 정보를 포함할 수 있는 유용한 단계입니다. 다음은 포함해야 하는 항목의 불완전한 목록입니다.

  • 작업이 수행하는 작업에 대한 자세한 설명
  • 필수 입력 및 출력 인수
  • 선택적 입력 및 출력 인수
  • 작업에서 사용하는 비밀
  • 작업에서 사용하는 환경 변수
  • 워크플로에서 작업을 사용하는 방법의 예제

일반적으로 README.md 파일에는 사용자가 작업을 사용하기 위해 알아야 할 모든 내용이 포함되어야 합니다. 유용한 정보가 될 수 있다고 생각되면 README.md에 포함합니다.

작업 릴리스 및 버전

퍼블릭 또는 프라이빗 여부와 관계없이, 다른 사용자가 사용할 작업을 개발하는 경우에는 업데이트 배포 방법을 제어하는 릴리스 관리 전략을 정의해야 합니다. 호환성에 영향을 미치는 필수 중요 수정 및 보안 패치를 포함한 주 버전 업데이트를 명확하게 문서화해야 합니다.

릴리스 및 버전 관리에 대한 유용한 정보

유용한 릴리스 관리 전략에는 버전 관리 권장 사항이 포함되어야 합니다. 사용자는 작업의 기본 분기를 참조해서는 안 됩니다. 기본 분기는 최신 코드(안정적일 수도 있고 아닐 수도 있음)를 포함할 가능성이 높고 워크플로가 중단될 수 있기 때문입니다. 대신, 사용자가 작업을 사용할 때 주 버전을 지정하고 문제가 발생하는 경우에만 더 구체적인 버전으로 직접 지정하는 것이 좋습니다. 이렇게 하려면 태그, 커밋의 SHA 또는 릴리스 이름을 지정한 특정 분기를 대상으로 GitHub Actions 워크플로를 구성해야 합니다. 이러한 릴리스 옵션을 좀 더 자세히 살펴보겠습니다.

태그

태그는 작업의 릴리스를 관리하는 좋은 방법입니다. 태그를 사용하면 사용자는 주 버전과 부 버전을 쉽게 구분할 수 있습니다. 다음은 릴리스를 만들 때 고려해야 할 유용한 방법의 목록입니다.

  • 릴리스 태그(예: v1.0.2)를 만들기 전에 릴리스 분기(예: release/v1)에서 릴리스를 만들고 유효성을 검사합니다.
  • 유의적 버전 관리 사용
  • 주 버전 태그(예: v1, v2)를 이동하여 현재 릴리스의 Git 참조를 가리킵니다.
  • 기존 워크플로를 중단하는 변경 내용에 대해 새 주 버전 태그(v2)를 도입합니다.
  • 베타 태그가 있는 주 버전을 릴리스하여 버전 상태를 표시합니다(예: v2-beta). 릴리스가 준비되면 -beta 태그를 제거할 수 있습니다.

다음은 각 옵션의 몇 가지 예입니다.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

커밋의 SHA 사용

태그는 유용하고 많은 곳에서 사용하지만, 태그 사용의 한 가지 단점은 태그를 삭제하거나 이동할 수 있다는 것입니다. Git을 사용하여 각 커밋은 고유하고 수정할 수 없는 계산된 SHA 값을 받습니다. 버전 관리에 대한 커밋 SHA를 사용하면 가장 안정적이고 안전한 방법으로 버전을 관리하고 작업을 사용할 수 있습니다. 그러나 일반적으로 Git에서 SHA 해시를 처음 몇 자로 축약할 수 있으며, Git는 참조를 인식합니다. 릴리스 관리를 위해 커밋의 SHA를 사용하는 경우 축약된 값이 아닌 전체 SHA 값을 사용해야 합니다.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

GitHub Marketplace에 작업 게시

워크플로를 빌드하고 개선하는 도구인 GitHub Marketplace를 표시하는 렌더링.

GitHub 커뮤니티와 작업을 공유할 준비가 되면 GitHub Marketplace에 작업을 게시하여 수백만 명의 GitHub 사용자와 공유할 수 있습니다. 모든 요구 사항이 충족되면 GitHub Marketplace에 게시된 작업이 즉시 게시됩니다. 요구 사항을 충족하지 않은 작업은 게시되기 전에 GitHub에서 검토해야 합니다. 리포지토리에 작업에 필요한 메타데이터 파일, 코드, 파일만 포함되어 있는지 확인해야 합니다. 작업에 대한 단일 리포지토리를 만들면 코드를 단일 단위로 태그, 릴리스, 패키지할 수 있습니다. 또한 GitHub는 GitHub Marketplace 페이지에서 작업의 메타데이터를 사용합니다.

다음은 GitHub Marketplace에 작업을 게시하기 위한 요구 사항입니다. Docker 컨테이너 기반 작업 및 JavaScript 기반 작업 모두에 적용됩니다.

  • 작업은 퍼블릭 리포지토리에 있어야 합니다.
  • 각 리포지토리에는 단일 작업이 포함되어야 합니다.
  • 작업의 메타데이터 파일(action.yml 또는 action.yaml)이 리포지토리의 루트 디렉터리에 있어야 합니다.
  • 작업의 메타데이터 파일에 있는 name은 GitHub Marketplace에서 고유해야 합니다.
    • 사용자 또는 조직 소유자가 작업을 게시하지 않는 한, 작업 이름은 GitHub의 사용자 또는 조직과 일치할 수 없습니다. 예를 들어 GitHub 조직만 github라고 지정된 이름의 작업을 게시할 수 있습니다.
    • name은 기존 GitHub Marketplace 범주와 일치할 수 없습니다.
    • name은 기존 GitHub 기능과 일치할 수 없습니다.

GitHub Marketplace에 새 릴리스로 태그한 다음 게시하여 만든 작업을 추가할 수 있습니다. GitHub에는 작업 릴리스를 게시할 수 있는 몇 가지 안내 단계가 있습니다. 이러한 단계에 대한 자세한 내용은 이 모듈 끝에 있는 요약 섹션에서 확인할 수 있습니다.