사용자 지정 액션 관리하기
사용자 지정 액션 관리하기
자체 액션을 만들고 관리하는 방법과 GitHub 커뮤니티가 공유하는 액션을 커스터마이즈하는 방법을 알아볼게요.
본문
액션 위치 선택
다른 사람이 사용할 액션을 개발하고 있다면 액션을 다른 애플리케이션 코드와 묶지 말고 자체 리포지토리에 보관하는 것을 권장해요. 그러면 다른 소프트웨어와 마찬가지로 액션을 버전 관리, 추적, 릴리스할 수 있어요.
액션을 자체 리포지토리에 저장하면 GitHub 커뮤니티가 액션을 발견하기 더 쉽고, 이슈를 수정하고 액션을 확장하는 개발자에게 코드베이스 범위를 좁혀주며, 액션의 버전 관리를 다른 애플리케이션 코드의 버전 관리에서 분리해줘요.
다른 사람에게 공개할 계획이 없는 액션을 구축하고 있다면 리포지토리의 아무 위치에나 액션 파일을 저장할 수 있어요. 액션, 워크플로, 애플리케이션 코드를 단일 리포지토리에 결합할 계획이라면 액션을 .github 디렉토리에 저장하는 것을 권장해요. 예를 들어 .github/actions/action-a와 .github/actions/action-b처럼요.
다른 플랫폼과의 호환성 보장
많은 사람이 GHE.com이나 GitHub Enterprise Server의 사용자 지정 도메인처럼 GitHub.com이 아닌 도메인에서 GitHub에 접근해요.
액션이 다른 플랫폼과 호환되도록 하려면 https://api.github.com 같은 API URL에 대한 하드코딩된 참조를 사용하지 마세요. 대신 다음을 할 수 있어요:
-
환경 변수 사용하기(변수 참조 참고):
- REST API의 경우
GITHUB_API_URL환경 변수를 사용하세요. - GraphQL의 경우
GITHUB_GRAPHQL_URL환경 변수를 사용하세요.
- REST API의 경우
-
올바른 URL을 자동으로 설정할 수 있는
@actions/github같은 툴킷 사용하기.
액션에 릴리스 관리 사용하기
다른 사람이 사용할 액션을 개발하고 있다면 릴리스 관리를 사용해 업데이트를 배포하는 방식을 제어하는 것을 권장해요. 사용자는 액션의 패치 버전에 필요한 중요 수정과 보안 패치가 포함되고 기존 워크플로와 여전히 호환되기를 기대할 수 있어요. 변경 사항이 호환성에 영향을 줄 때마다 새 메이저 버전을 릴리스하는 것을 고려해야 해요.
이 릴리스 관리 방식에서 사용자는 액션의 기본 분기를 참조하지 않아야 해요. 기본 분기에는 최신 코드가 포함될 가능성이 커서 불안정할 수 있기 때문이에요. 대신 사용자에게 액션을 사용할 때 메이저 버전을 지정하라고 권장하고, 문제가 발생할 때만 더 구체적인 버전으로 안내하세요.
특정 액션 버전을 사용하려면 사용자가 GitHub Actions 워크플로를 태그, 커밋 SHA, 또는 릴리스 이름의 분기를 대상으로 구성할 수 있어요.
릴리스 관리에 태그 사용하기
[!NOTE] 공급망 공격과 릴리스의 우발적 변경을 방지하기 위해 불변 릴리스(immutable releases)를 활성화했다면 불변 릴리스와 태그를 사용해 액션 릴리스 관리하기를 대신 참고하세요.
액션 릴리스 관리에는 태그를 사용하는 것을 권장해요. 이 방식을 사용하면 사용자가 메이저 버전과 마이너 버전을 쉽게 구분할 수 있어요:
- 릴리스 분기(예:
release/v1)에서 릴리스를 개발하고 검증하세요. - 시맨틱 버전을 사용해 릴리스 태그(예:
v1.0.1)로 릴리스를 만드세요. 자세한 내용은 리포지토리에서 릴리스 관리하기를 참고하세요. - 메이저 버전 태그(예:
v1)를 현재 릴리스의 Git ref를 가리키도록 이동하세요. 자세한 내용은 Git 기초 - 태깅을 참고하세요. - 액션의 입력을 변경하는 것처럼 기존 워크플로를 깨뜨릴 변경 사항에 대해 새 메이저 버전 태그(예:
v2)를 도입하세요.
태그 참조 문법
이 예시는 사용자가 메이저 버전 태그를 참조하는 방법을 보여줘요:
steps:
- uses: actions/javascript-action@v1
이 예시는 사용자가 특정 패치 릴리스 태그를 참조하는 방법을 보여줘요:
steps:
- uses: actions/[email protected]
릴리스 관리에 분기 사용하기
릴리스 관리에 분기 이름을 사용하는 것을 선호한다면 이 예시는 이름 있는 분기를 참조하는 방법을 보여줘요:
steps:
- uses: actions/javascript-action@v1-beta
릴리스 관리에 커밋 SHA 사용하기
각 Git 커밋은 계산된 SHA 값을 받으며, 이 값은 고유하고 불변(immutable)이에요. 액션 사용자는 커밋 SHA 값에 의존하는 것을 선호할 수 있는데, 삭제되거나 이동될 수 있는 태그를 지정하는 것보다 이 방식이 더 신뢰할 수 있기 때문이에요. 다만 이는 사용자가 액션에 대한 이후 업데이트를 받지 못한다는 뜻이에요. 커밋의 전체 SHA 값을 사용해야 하며 축약된 값은 사용하면 안 돼요.
steps:
- uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f
액션용 README 파일 만들기
사람들이 액션을 사용하는 방법을 배울 수 있도록 README 파일을 만드는 것을 권장해요. README.md에 다음 정보를 포함할 수 있어요:
- 액션이 수행하는 작업에 대한 상세 설명
- 필수 입력 및 출력 인수
- 선택 입력 및 출력 인수
- 액션이 사용하는 비밀
- 액션이 사용하는 환경 변수
- 워크플로에서 액션을 사용하는 방법 예시