Homebrew 7.0.0에서 Homebrew/actions/*@master 참조가 제거됐으므로, 해당 참조를 계속 사용하지 말고 CalVer 릴리스나 전체 커밋 SHA로 바꾸세요. 변경은 격리된 맥OS CI 작업에서 입력, 출력, 실제 빌드 결과까지 검증한 뒤 반영해야 합니다. 단순히 @main으로 바꾸는 것은 장기 고정책이 아닙니다. Homebrew 7.0.0 공식 발표와 공식 마이그레이션 기록을 기준으로 확인하세요.
Homebrew 공식과 관련 프로젝트를 관리하며 오래된 참조를 고쳐야 하는 유지보수자에게 적합합니다.
맥OS CI에서 Action 버전 변경을 안전하게 검증해야 하는 엔지니어도 참고하세요.
개발 플랫폼 담당자는 팀의 버전 고정 및 롤백 절차를 점검할 수 있습니다.
마지막 업데이트: 2026년 11월 16일. Homebrew 공식 발표와 마이그레이션 기록, Homebrew/actions 저장소를 기준으로 내용을 확인했습니다. 배포 태그와 마이그레이션 안내는 바뀔 수 있으니 적용 직전에 공식 자료와 대상 워크플로를 다시 확인하세요.
01 작업 전: 어떤 참조가 막혔는지 먼저 확인합니다
Homebrew 7의 변경은 @master라는 참조가 새 이름으로 자동 연결되는 방식이 아닙니다. GitHub Actions는 삭제된 브랜치 참조를 다른 참조로 자동 전환하지 않으므로, 해당 문자열이 들어간 작업은 실제로 해결되지 않을 수 있습니다. 공식 발표는 @master 제거와 함께 @main 사용도 마이그레이션 대상으로 안내합니다. 따라서 일시적인 네트워크 오류로 간주하거나 @main만 넣고 끝내지 마세요.
Homebrew 7 뒤에 @master 참조가 작동하지 않는 이유는 무엇인가요?
Action의 uses 값은 저장소 안에서 지정한 태그나 브랜치, 커밋을 가리킵니다. Homebrew/actions에서 @master 참조가 제거되면, 그 이름을 지정한 워크플로는 해당 참조를 찾지 못할 수 있습니다. 정확한 실패 로그와 현재 참조 상태는 Homebrew/actions 공식 저장소에서 대조하세요.
먼저 저장소와 실행 스크립트에서 참조를 찾습니다. 아래 명령은 예시이며, 저장소 구조에 따라 검색 대상 경로를 추가하세요.
grep -RInE 'Homebrew/actions/[^[:space:]]+@(master|main)' \
.github scripts
검색 결과를 그대로 일괄 치환하지 말고, 각 참조의 역할과 연결된 작업을 기록합니다.
- [ ] 워크플로 파일의
uses참조를 찾았습니다. - [ ] 재사용 워크플로와 복합 액션, 스크립트 안의 참조도 확인했습니다.
- [ ] 각 액션의 목적, 입력값, 출력값을 기록했습니다.
- [ ]
@master와@main을 구분해 마이그레이션 대상으로 표시했습니다. - [ ] 변경 대상 브랜치와 검증 담당자를 정했습니다.
@master는 공식 발표에서 제거된 참조입니다. @main은 그대로 두어도 된다는 보증이 아니라, 공식 기록이 이전을 권하는 대상입니다. 이 차이를 리뷰 항목에 남기면 단순 문자열 치환과 실제 버전 고정을 구별할 수 있습니다.
02 마이그레이션 계획: 팀에 맞는 버전 고정 방식을 선택합니다
Homebrew/actions의 현재 릴리스 목록과 각 액션의 사용 정보를 확인한 뒤 참조를 선택하세요. 사용 가능한 태그는 바뀔 수 있으므로 특정 태그가 언제나 유효하다고 가정하지 말고, 공식 저장소의 기록을 기준으로 확인해야 합니다.
CalVer와 전체 SHA 중 무엇을 선택해야 하나요?
- CalVer 릴리스 태그는 사람이 읽고 검토하기 쉽습니다. 팀이 릴리스 변경을 주기적으로 확인하고 업데이트하는 절차를 운영한다면 후보가 됩니다. 실제 태그와 해당 액션의 존재 여부는 공식 저장소에서 확인하세요.
- 전체 커밋 SHA는 특정 커밋을 가리키도록 고정할 때 적합합니다. GitHub는 전체 길이 커밋 SHA를 액션을 고정하는 안전한 방법으로 안내합니다. 변경 시에는 새 SHA를 검토하고 의도적으로 업데이트해야 합니다. 자세한 기준은 GitHub의 보안 사용 지침을 참고하세요.
다음 조건으로 결정하면 됩니다.
- 릴리스 태그를 정기 점검하고 검토된 버전으로 올릴 책임자가 있다면 CalVer를 선택합니다.
- 변경을 커밋 단위로 검토하고 고정된 소스를 승인하는 절차가 있다면 전체 SHA를 선택합니다.
- 어느 쪽이든 업데이트 담당자나 검토 주기를 정할 수 없다면, 먼저 소유자와 갱신 절차를 정하세요.
@main을 장기 고정책으로 남기는 방식으로 대체하지 않습니다.
GitHub 워크플로에서 액션 참조를 관리하는 방법은 워크플로 구문 문서와 워크플로 의존성 잠금 파일 안내도 함께 확인하세요. 팀에서 허용하는 참조 형식은 저장소 Actions 설정과도 일치해야 합니다.
03 격리 시험: 참조뿐 아니라 동작 결과까지 확인합니다
시험용 브랜치에서 마이그레이션 목록을 한 항목씩 변경하세요. 예시의 조직, 저장소, 액션 이름, 릴리스 태그와 SHA는 모두 자리표시자입니다. 실제 사용 값은 공식 저장소에서 확인한 뒤 넣어야 합니다.
# CalVer 릴리스 태그를 쓰는 예시
- uses: <조직>/<저장소>/<액션>@<CalVer-릴리스-태그>
# 전체 커밋 SHA를 쓰는 예시
- uses: <조직>/<저장소>/<액션>@<전체-커밋-SHA>
그다음 대상 macOS CI에서 최소한의 시험 작업을 실행합니다. 실제 macOS 환경에서 재현할 준비가 필요하다면 CALMVPS의 원격 맥 환경 안내를 먼저 살펴보고, 현재 이용 조건은 요금 안내에서 확인하세요. 이 안내만으로 특정 환경이나 기능의 제공 여부를 단정하지 말고, 시험에 필요한 조건을 확인한 뒤 결정해야 합니다.
- [ ] 액션 참조가 해석되고 작업이 시작되는지 확인합니다.
- [ ] 기존 워크플로 입력값이 새 버전에서도 유효한지 확인합니다.
- [ ] 액션 출력값을 읽는 다음 단계가 의도한 값을 받는지 확인합니다.
- [ ] 권한과 작업 순서가 프로젝트의 기대와 맞는지 점검합니다.
- [ ] Homebrew 작업의 결과를 이전 기준과 비교해 재현성을 확인합니다.
- [ ] Runner, macOS 버전, 워크플로 커밋을 로그에 남깁니다.
입력값이나 출력 이름이 같을 것이라고 추정하지 마세요. GitHub Actions 워크플로 구문에서 워크플로 선언을 확인하고, 실제 작업 로그와 후속 단계 결과로 프로젝트에서 쓰는 동작을 검증해야 합니다. 이 글에서는 특정 Runner나 Homebrew 작업의 시험 성공을 주장하지 않습니다. 결과는 대상 환경에서 직접 확인하고 기록해야 합니다.
04 시험 결과를 근거로 배포하고 되돌립니다
시험 로그를 검토한 다음 저장소별로 변경을 반영하세요. 여러 저장소가 같은 액션을 쓰더라도 한꺼번에 일괄 적용하지 말고, 먼저 영향 범위가 작은 워크플로에서 확인한 뒤 확장하는 편이 실패 원인을 좁히기 쉽습니다.
- [ ] 마이그레이션 전후 로그와 작업 결과를 비교했습니다.
- [ ] 승인된 CalVer 태그 또는 전체 SHA를 변경 기록에 남겼습니다.
- [ ] 실패 시 되돌릴 참조와 담당자를 정했습니다.
- [ ] 다음 업데이트 검토 시점과 공식 변경 공지를 다시 확인할 조건을 기록했습니다.
- [ ] 저장소별 배포 상태를 확인한 뒤 다음 대상으로 진행합니다.
롤백은 실패한 참조를 다시 넣는 것이 아닙니다. 기존 로그나 저장소 기록으로 동작을 확인한 버전으로 되돌리고, 문제가 난 단계와 오류를 함께 남기세요. GitHub의 보안 사용 지침과 저장소 정책을 바탕으로 허용 가능한 참조를 정하면, 복구 과정에서 확인되지 않은 브랜치 참조가 다시 들어가는 일을 막을 수 있습니다.
@master를 @main으로 바꾸는 것만으로는 검증도 버전 관리도 끝나지 않습니다. 팀이 이미 쓸 수 있는 Mac 환경을 갖췄다면 그 환경에서 격리 시험을 진행하세요. 반대로 시험용 Mac이 없고 실제 macOS 작업을 반복 검증해야 한다면, 직접 장비를 마련하는 비용과 운영 부담, 다른 클라우드 환경에서 생길 수 있는 macOS 도구 체인 제약을 비교한 뒤 원격 맥을 검토할 수 있습니다. 단발성 시험이라면 구매보다 임시 환경이 나을 수 있지만, 지속적인 고정 부하나 물리 장치가 필요한 작업에는 렌탈이 맞지 않을 수 있습니다. 워크플로를 먼저 시험하고 요구 조건을 확정한 뒤, 필요하다면 한국 주문 안내에서 이용 조건을 확인하세요.