자동 릴리스는 버전 태그를 푸시하거나 GitHub Actions 워크플로를 수동으로 시작하면 샌드박스 플러그인을 빌드하고 게시합니다. 귀하의 Atmosphere 계정이 패키지 프로필과 릴리스 레코드를 소유합니다. GitHub가 승인된 워크플로를 식별하고, 릴리스 서비스가 저장소에 계정 자격 증명을 저장하지 않고 결과를 검증하고 게시합니다.
컴퓨터에서 시작하는 릴리스에는 emdash-plugin publish를 사용하세요. GitHub Actions가 릴리스를 빌드하고 게시해야 하는 경우 이 가이드를 사용하세요.
전제 조건
시작하기 전에 다음을 준비하세요:
- 샌드박스 EmDash 플러그인이 포함된 공개 GitHub 저장소.
slug,publisher,license, 작성자, 보안 연락처가 포함된 유효한emdash-plugin.jsonc.repo를 정규 GitHub URL로 설정하거나 대화형 설정 중에 입력하세요.package.json의 버전, 또는 레지스트리 전용 플러그인의 경우emdash-plugin.jsonc의 버전.publisher로 지정된 Atmosphere 계정.- 저장소에 GitHub Actions 시크릿을 추가할 수 있는 권한.
- 패스키를 지원하는 브라우저. 릴리스 승인에는 사용자 검증이 필요합니다.
워크플로를 구성하기 전에 매니페스트 검사를 실행하세요:
pnpm exec emdash-plugin validate자동 릴리스 설정
-
패키지를 소유하는 Atmosphere 계정으로 플러그인 CLI에 로그인합니다.
pnpm exec emdash-plugin login alice.example.comCLI는 이 로컬 게시 세션을 프로젝트 외부에 저장합니다. GitHub Actions는 이를 수신하지 않습니다.
-
패키지 프로필을 준비하고 워크플로를 생성합니다.
pnpm exec emdash-plugin release setup이 명령은
emdash-plugin.jsonc에서 패키지 메타데이터를 읽습니다. 패키지 프로필이 없으면 생성을 제안합니다. 프로필이 존재하지만 위임 릴리스 설정이 없으면 기존 패키지 메타데이터를 보존하면서 추가를 제안합니다.설정은 릴리스에 승인이 필요한 시점을 묻습니다:
- 플러그인 권한이 증가할 때가 기본값입니다. 선언된 접근 권한이 최신 릴리스 대비 확장되면 릴리스가 승인을 대기합니다.
- 모든 릴리스에 대해는 모든 버전에 대해 승인을 요구합니다.
로그인된 Atmosphere 계정이 초기 승인자가 됩니다. 프로필은 또한 패키지를 정규 GitHub 저장소 URL에 바인딩하고 검증 가능한 출처를 요구합니다.
워크플로 파일이 이미 존재하는 경우 프로필 단계만 실행하세요:
pnpm exec emdash-plugin profile setup비대화형 터미널에서는
--yes를 전달하여 기본 승인 정책을 수락합니다. 매니페스트에repo가 포함되어 있지 않을 때는--repository <https-url>을, 모든 릴리스에 대해 승인을 요구하려면--confirmation always를 전달하세요. -
생성된 워크플로를 검토하고 커밋합니다.
이 명령은
.github/workflows/emdash-release.yml을 생성합니다. 파일을 푸시하지 않으며--force를 전달하지 않는 한 기존 워크플로를 대체하지 않습니다.생성된 워크플로는
v*와 일치하는 버전 태그와workflow_dispatch를 통해 실행됩니다.contents: read,id-token: write,attestations: write를 부여하고, 서드파티 Actions를 전체 커밋 식별자에 고정하고, 하나의 플러그인 번들을 빌드하고, 해당 바이트에 대한 GitHub 빌드 출처를 생성하고, 두 파일을 모두 EmDash 릴리스 Action에 전달합니다. -
릴리스 서비스 대시보드를 열고 동일한 Atmosphere 계정으로 로그인합니다.
Authorize publishing을 선택합니다. 계정 제공자가 정확한 위임 권한을 표시합니다. 유지된 부여는 패키지 릴리스 레코드를 생성하고 패키지 또는 리스팅 이미지 Blob을 업로드할 수 있습니다. 패키지 프로필을 생성하거나 편집하거나, 릴리스를 업데이트하거나 삭제하거나, 다른 컬렉션에 쓸 수는 없습니다.
-
워크플로 초대를 생성합니다.
emdash-plugin.jsonc에서 플러그인 ID를 입력한 다음 Create invitation을 선택합니다. 일회용 값을 GitHub 저장소에EMDASH_CONNECTION_INVITATION이라는 이름의 Actions 시크릿으로 추가합니다.초대는 30분 동안 유효하며 지정된 플러그인만 연결할 수 있습니다. 워크플로가 소비하기 전에 만료되면 새 초대를 생성하세요.
-
릴리스 워크플로를 시작합니다.
버전 태그를 생성하기 전에 패키지 버전을 업데이트합니다. 다음 명령으로
1.2.3릴리스를 시작합니다:git tag v1.2.3 git push origin v1.2.3저장소의 GitHub Actions 페이지에서 Run workflow를 선택할 수도 있습니다.
-
첫 실행 시 워크플로 연결을 승인합니다.
Action이 GitHub 작업 요약에 링크를 작성하고 대기합니다. 링크를 열고 플러그인, 저장소, 워크플로 파일, 브랜치 또는 태그, 환경을 확인합니다.
태그 트리거 실행의 경우 All version tags 또는 Only this tag를 선택합니다. 브랜치 트리거 요청은 해당 브랜치만 포함합니다. 서비스는 GitHub 저장소 및 소유자 ID와 선택된 ref 및 환경 범위를 저장합니다. 이후 실행은 이 정책과 일치해야 합니다.
-
필요할 때 릴리스를 승인합니다.
플러그인 권한을 확장하는 릴리스 또는 모든 릴리스에 대한 확인이 구성된 프로필은 Awaiting approval 상태가 됩니다. Action 출력 또는 릴리스 대시보드에서 승인 URL을 엽니다. 승인 계정에 패스키가 아직 없다면 등록하고, 권한 변경을 검토한 다음 릴리스를 승인하거나 거부합니다.
Action의 기본 설정은 릴리스가 Awaiting approval에 도달하면 성공적으로 반환합니다. 서비스 워크플로는 브라우저 결정을 계속 대기하며 승인 후 게시합니다.
릴리스 서비스가 검증하는 내용
서비스는 릴리스를 작성하기 전에 다음 검사를 완료합니다:
- GitHub OpenID Connect(OIDC) 토큰이 승인된 저장소, 소유자, 워크플로, ref, 환경, 커밋, 실행, GitHub 호스팅 러너를 지정합니다.
- 패키지 프로필이 존재하고, 게시자가 서명했으며, 위임 릴리스 설정을 포함하고, 동일한 정규 GitHub 저장소를 지정합니다.
- 요청된 패키지와 버전이 빌드된 플러그인 번들과 일치합니다.
- 패키지 체크섬이 업로드된 바이트와 일치합니다.
- GitHub 출처가 동일한 번들, 저장소, 워크플로, 커밋, 실행을 포함합니다.
- 릴리스 레코드의 선언된 접근 권한이 번들 매니페스트와 일치합니다.
- 버전 레코드가 아직 존재하지 않습니다.
- 필요한 패스키 승인이 정확한 검증 결과와 현재 프로필 리비전을 포함합니다.
Action은 각 서비스 호출에 대해 새로운 GitHub OIDC 토큰을 요청합니다. 번들 및 출처 파일은 워크플로가 승인된 후에만 비공개 임시 스토리지에 들어갑니다. 서비스는 검증된 패키지 및 이미지 바이트를 게시자의 개인 데이터 서버(PDS)에 업로드하고, 그곳에서 릴리스 레코드를 생성하며, 불변의 체크섬 주소 URL을 통해 검증된 출처를 노출합니다.
권한 경계
각 자격 증명에는 하나의 역할이 있습니다:
| 자격 증명 | 사용 주체 | 권한 |
|---|---|---|
| 로컬 CLI OAuth 세션 | emdash-plugin profile setup | 로컬 확인 후 게시자 소유의 패키지 프로필을 생성하거나 업데이트합니다. |
| GitHub OIDC 토큰 | 릴리스 Action | 서비스에 하나의 GitHub 워크플로 실행을 식별합니다. AT Protocol 쓰기 접근 권한은 부여하지 않습니다. |
| 릴리스 서비스 위임 | 릴리스 서비스 | 패키지 릴리스 레코드를 생성하고 필요한 Blob을 업로드합니다. |
| 게시자 애플리케이션 세션 | 릴리스 대시보드 | 워크플로 연결을 승인하고 위임 게시를 취소합니다. |
| 승인자 세션 및 패스키 | 승인 페이지 | 체크섬에 바인딩된 하나의 릴리스 검증을 승인하거나 거부합니다. |
| Cloudflare Access ID | 서비스 운영자 콘솔 | 호스팅된 서비스를 운영합니다. 게시자 또는 승인자를 나타내지 않습니다. |
서비스는 게시자와 승인자 상태를 별도로 저장합니다. 릴리스를 보기 위해 로그인해도 운영자 접근 권한이 부여되지 않으며, 운영자 ID는 게시자로서 릴리스를 승인할 수 없습니다.
Action 동작
생성된 워크플로는 apps/release-action의 Action을 사용합니다. Action은 빌드된 번들과 원시 Sigstore 출처, 또는 체크섬에 바인딩된 HTTPS 아티팩트 소스를 포함하는 호환성 release-file을 수락합니다. release-file을 번들 또는 출처 입력과 결합하지 마세요.
표준 생성된 워크플로는 다음 입력을 제공합니다:
| 입력 | 값 |
|---|---|
service-url | 릴리스 서비스 HTTPS 오리진. |
publisher-did | 패키지 프로필과 릴리스를 소유하는 DID. |
connection-invitation | 첫 연결 시 EMDASH_CONNECTION_INVITATION. |
bundle-file | emdash-plugin bundle이 생성하는 단일 tarball. |
provenance-file | actions/attest-build-provenance의 원시 bundle-path 출력. |
Action은 다음 출력을 반환합니다:
| 출력 | 의미 |
|---|---|
connection-url | 첫 실행 시 워크플로 승인용 브라우저 URL. |
intent-id | 릴리스 인텐트 식별자. |
state | Published, 터미널, 또는 awaiting_approval 상태. |
approval-url | 패스키 승인이 필요할 때의 브라우저 URL. |
release-uri | 게시된 릴리스 AT URI. |
release-cid | 게시된 릴리스 레코드 CID. |
reason-code | 터미널 인텐트의 안정적인 사유. |
선택적 입력, 사용자 정의 URL 소스 워크플로, 폴링 제어, 정확한 출력 동작에 대해서는 Action 참조를 확인하세요.
문제 해결
PACKAGE_PROFILE_REQUIRED
패키지 프로필이 없거나, 위임 릴리스 설정이 누락되었거나, 비정규 저장소 URL을 사용하고 있거나, GitHub 워크플로와 다른 저장소를 지정하고 있습니다.
게시자 계정으로 로컬에서 프로필 설정을 실행한 다음 워크플로를 다시 시작하세요:
pnpm exec emdash-plugin profile setup이 검사는 서비스가 번들 또는 출처 업로드를 수락하기 전에 실행됩니다.
공개 저장소 필요
GitHub은 비공개 및 내부 저장소에 대해 비공개 Sigstore 신뢰 루트를 사용합니다. 릴리스 검증자는 현재 공개 GitHub 출처만 신뢰합니다. 릴리스 워크플로를 공개 저장소로 이동하거나 emdash-plugin publish로 로컬에서 게시하세요.
초대 만료 또는 무효
릴리스 대시보드에서 다른 초대를 생성하고 EMDASH_CONNECTION_INVITATION을 교체하세요. 30분 이내에 워크플로를 시작하세요. 초대는 일회용이며 하나의 플러그인 ID로 범위가 제한됩니다.
WORKLOAD_NOT_ALLOWED
GitHub 저장소, 소유자, 워크플로 파일, ref, 또는 환경이 승인된 워크플로 정책과 일치하지 않습니다. 릴리스 대시보드를 열고 의도한 범위로 새 워크플로 연결을 승인하세요.
PROFILE_FETCH_FAILED
서비스가 게시자의 PDS에서 프로필을 검증할 수 없었습니다. 계정 제공자가 사용 가능할 때 다시 시도하세요. 프로필이 제거되거나 변경된 경우 emdash-plugin profile setup을 실행하세요.
POLL_TIMEOUT
Action이 워크플로 승인, 릴리스 승인, 또는 게시가 완료되기 전에 timeout-minutes에 도달했습니다. 다시 실행하기 전에 릴리스 대시보드에서 인텐트 상태를 확인하세요. 동일한 GitHub Actions 실행의 재실행은 멱등성 키를 재사용합니다.
자동 게시 취소
릴리스 대시보드에서 Turn off automated publishing을 선택합니다. 취소는 유지된 릴리스 위임을 지웁니다. 기존 패키지 프로필, 릴리스, 조정 라벨, 설치된 플러그인, 대시보드 로그인은 변경되지 않습니다.
다음 자동 릴리스 전에 게시를 다시 연결하고 워크플로를 다시 승인하세요.
관련 문서
- Bundling and publishing은 로컬 게시 및 번들 검증을 다룹니다.
- The plugin manifest는 패키지 메타데이터와 선언된 접근 권한을 정의합니다.
- Capabilities and security는 릴리스 승인 및 설치 시 검토되는 권한을 설명합니다.
- The plugin registry는 발견, 조정, 설치 검증을 설명합니다.