사용자 지정 작업 관리

사용자 고유 작업을 만들어 관리하고 GitHub 커뮤니티에서 공유하는 작업을 사용자 지정하는 방법을 알아봅니다.

이 문서의 내용

작업 위치 선택

다른 사람이 사용할 작업을 개발하는 경우 작업을 다른 애플리케이션 코드와 함께 묶는 대신 자체 리포지토리에 유지하는 것이 좋습니다. 이를 통해 다른 소프트웨어처럼 작업을 버전 관리하고, 추적하고, 릴리스할 수 있습니다.

작업을 자체 리포지토리에 저장하면 GitHub 커뮤니티에서 작업을 더 쉽게 검색하고, 개발자가 문제를 수정하고 작업을 확장할 수 있는 코드 베이스의 범위를 좁히며, 작업의 버전 관리와 다른 애플리케이션 코드의 버전 관리가 분리됩니다.

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

다른 플랫폼과의 호환성 보장

많은 사람들이 GitHub.com 이외의 도메인(예: GHE.com 또는 GitHub Enterprise Server에 대한 사용자 지정 도메인)에서 GitHub에 액세스합니다.

작업이 다른 플랫폼과 호환되도록 하려면 API URL(예: https://api.github.com)에 대해 하드 코딩된 참조는 사용하지 마세요. 대신 다음을 사용할 수 있습니다.

  • 환경 변수 사용(변수 참조 참조):

    • REST API의 경우 GITHUB_API_URL 환경 변수를 사용합니다.
    • GraphQL의 경우 GITHUB_GRAPHQL_URL 환경 변수를 사용합니다.

  • 올바른 URL을 자동으로 설정할 수 있는 @actions/github와 같은 도구 키트를 사용합니다.

작업에 릴리스 관리 사용

이 섹션에서는 릴리스 관리를 사용하여 예측 가능한 방식으로 작업에 대한 업데이트를 배포하는 방법을 설명합니다.

릴리스 관리 모범 사례

다른 사람이 사용할 작업을 개발하는 경우 릴리스 관리를 사용하여 업데이트를 배포하는 방법을 제어하는 것이 좋습니다. 사용자는 작업의 패치 버전에 필요한 중요 수정 사항 및 보안 패치가 포함되어 있으면서도 기존 워크플로와 계속 호환될 것으로 기대할 수 있습니다. 변경 내용이 호환성에 영향을 미칠 때마다 새 주 버전을 릴리스하는 것이 좋습니다.

이 릴리스 관리 접근 방식에서는 사용자가 작업의 기본 분기를 참조해서는 안 됩니다. 최신 코드를 포함할 가능성이 크고 결과적으로 불안정할 수 있기 때문입니다. 대신, 사용자가 작업을 사용할 때 주 버전을 지정하고 문제가 발생하는 경우에만 더 구체적인 버전으로 안내하도록 하는 것이 좋습니다.

특정 작업 버전을 사용하기 위해 사용자는 태그, 커밋의 SHA 또는 릴리스에 대해 명명된 분기를 대상으로 하도록 GitHub Actions 워크플로를 구성할 수 있습니다.

릴리스 관리에 태그 사용

작업 릴리스 관리에 태그를 사용하는 것이 좋습니다. 이 방법을 사용하면 사용자가 주 버전과 부 버전을 쉽게 구분할 수 있습니다.

  • 릴리스 태그(예: v1.0.2)를 만들기 전에 릴리스 분기(예: release/v1)에서 릴리스를 만들고 유효성을 검사합니다.
  • 의미 체계 버전 관리를 사용하여 릴리스를 만듭니다. 자세한 내용은 리포지토리에서 릴리스 관리을(를) 참조하세요.
  • 주 버전 태그(예: v1, v2)를 이동하여 현재 릴리스의 Git 참조를 가리킵니다. 자세한 내용은 Git 기본 사항 - 태그 지정을 참조하세요.
  • 기존 워크플로를 중단하는 변경 내용에 대해 새 주 버전 태그(v2)를 도입합니다. 예를 들어 작업의 입력을 변경하는 것은 호환성이 손상되는 변경입니다.
  • 주 버전은 처음에 상태를 나타내기 위해 beta 태그(예: v2-beta)를 사용하여 릴리스될 수 있습니다. -beta 태그는 준비가 되면 제거할 수 있습니다.

이 예제에서는 사용자가 주 릴리스 태그를 참조하는 방법을 보여 줍니다.

steps:
    - uses: actions/javascript-action@v1

이 예제에서는 사용자가 특정 패치 릴리스 태그를 참조하는 방법을 보여 줍니다.

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

릴리스 관리에 분기 사용

릴리스 관리에 분기 이름을 사용하려는 경우 이 예제에서는 명명된 분기를 참조하는 방법을 보여 줍니다.

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

릴리스 관리에 커밋의 SHA 사용

각 Git 커밋은 고유하고 변경할 수 없는 계산된 SHA 값을 수신합니다. 이 방법은 삭제되거나 이동할 수 있는 태그를 지정하는 것보다 더 안정적일 수 있으므로 작업의 사용자는 커밋의 SHA 값에 의존하는 것을 선호할 수 있습니다. 그러나 이는 사용자가 작업에 대한 추가 업데이트를 받지 못한다는 것을 의미합니다. 약식 값이 아닌 커밋의 전체 SHA 값을 사용해야 합니다.

steps:
    - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

작업에 대한 추가 정보 파일 만들기

사용자가 작업을 사용하는 방법을 배울 수 있도록 추가 정보 파일을 만드는 것이 좋습니다. 이 정보를 README.md에 포함할 수 있습니다.

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