gitea-agent/harness/agents/release/skills/gitea-release/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
gitea-release	승인된 Gitea 버전을 준비·태깅하고 산출물을 게시한다.	0.1.0	genichin, Hermes Agent	MIT	linux	hermes tags related_skills gitea release worktree tag artifact gitea-repository-cache-bootstrap

Gitea Release

Gitea repository cache를 사용해 버전 준비, 검증, 태깅과 프로젝트별 산출물 게시를 수행한다. Cache 규칙은 Repository cache 운영 지침을 정본으로 사용한다.

사용 시점

• exact owner/repository의 새 버전 준비를 요청받았을 때
• 준비된 commit을 태깅하고 승인된 산출물을 게시하도록 요청받았을 때
• 기존 릴리즈의 tag, commit과 게시 산출물을 검증할 때

Issue 구현, PR merge, 임의 버전 선택, 기존 tag 이동, artifact 덮어쓰기 또는 deployment에는 사용하지 않는다.

책임 분리

공통 릴리즈 처리

이 스킬이 담당한다.

• repository cache 검증과 fetch
• release lock과 worktree 관리
• 버전 변경 파일 제한
• 간단한 준비 검증
• local commit 생성과 commit tree 검증
• 승인된 commit에 tag 생성·push
• 프로젝트별 게시 절차 호출
• 원격 tag와 artifact readback
• 성공한 worktree 정리

프로젝트별 처리

Target repository의 release contract가 담당한다.

• version source와 함께 변경할 lockfile
• test, lint와 build 명령
• artifact 종류와 이름
• 대상 platform과 build context
• registry, package namespace와 인증 secret 이름
• smoke test와 게시 명령
• digest, checksum 또는 provenance 검증

Release contract가 없거나 모호하면 기존 workflow, build metadata와 문서를 읽어 확인된 사실만 보고한다. 이미지 이름, registry, credential, 명령 또는 artifact를 추측하지 않는다.

승인 계약

준비 승인

버전 변경과 local commit을 시작하려면 다음이 필요하다.

• exact owner/repository
• exact version과 tag
• 버전 파일 변경에 대한 명시적 승인

Agent는 버전을 선택, 증가, 정규화 또는 교체하지 않는다.

게시 승인

Tag 또는 artifact를 외부에 게시하려면 다음이 필요하다.

• exact owner/repository
• exact version과 tag
• 준비된 full commit SHA
• exact artifact와 게시 대상

브랜치명, 축약 SHA, HEAD, moving tag 또는 unstated default는 게시 승인이 아니다.

Release worktree 모델

Repository마다 동시에 하나의 release workflow만 허용한다.

/opt/data/gitea-agent/repositories/<owner>/<repository>/
├── locks/release.lock
└── worktrees/release/
    ├── state.json
    └── checkout/

• release.lock을 전체 workflow 동안 유지한다.
• Cache fetch, worktree 등록 변경과 제거에는 release.lock → repository.lock 순서로 획득한다.
• Worktree는 확인된 원격 default-branch full SHA의 detached HEAD로 생성하고 lock한다.
• 기존 release worktree를 reset, clean, rebase, checkout, force-remove 또는 덮어쓰지 않는다.
• 실패한 release worktree는 증거 보존을 위해 자동 제거하지 않는다.

state.json에는 최소한 schema gitea-agent.release-worktree/v1, repository identity, base SHA, requested version·tag, prepared commit SHA와 단계 상태를 기록한다. Credential, PID 또는 secret 값은 기록하지 않는다.

절차

1. Target과 cache 확인

1. 요청의 repository, version, tag와 승인 범위를 추출한다.
2. Gitea MCP로 authenticated identity, repository metadata, default branch와 SHA를 읽는다.
3. operations/repository-cache.md에 따라 cache를 검증하거나 초기화한다.
4. Release lock 아래 repository lock을 획득해 exact origin을 prune/fetch한다.
5. Gitea default-branch SHA와 local mirror ref 일치를 확인한다.

완료 조건: authoritative repository identity와 local cache가 같은 full SHA를 가리킨다.

2. Release worktree 생성

1. 기존 release worktree, Git registration과 state를 함께 조사한다.
2. 대상이 모두 없을 때만 exact default-branch SHA에서 detached worktree를 만든다.
3. Worktree를 release 용도로 lock하고 state.json을 원자적으로 기록한다.
4. HEAD, detached 상태, common Git directory와 clean 상태를 다시 확인한다.

완료 조건: release worktree가 확인된 base SHA에서 clean·detached·locked 상태다.

3. 프로젝트 계약 조사

1. search_files와 read_file로 version metadata, lockfile, test, build, 기존 workflow와 release 문서를 읽는다.
2. Version 변경 파일, 준비 검증과 게시 adapter를 구분한다.
3. 정확한 게시 대상이나 credential 가용성을 확인할 수 없으면 수정 전에 중단한다.

완료 조건: 변경 파일 allowlist, 준비 검증 명령과 프로젝트별 게시 절차가 명확하다.

4. 버전 변경과 준비 commit

1. 승인된 exact version만 allowlist 파일에 반영한다.
2. Project-defined 준비 test와 정적 검사를 실행한다.
3. 수정·미추적 파일 전체를 검사하고 allowlist 밖의 변경이 있으면 중단한다.
4. Exact path만 stage하고 staged diff, secret, 삭제와 whitespace 오류를 검토한다.
5. Non-amended local commit을 생성한다.
6. Commit의 parent, tree, version·tag 일치와 clean worktree를 검증한다.
7. state.json에 prepared full SHA와 검증 결과를 기록한다.

완료 조건: 승인된 버전 변경만 포함한 하나의 검증된 local commit이 존재한다.

5. 게시 gate

다음을 모두 확인한다.

• 게시 승인이 exact prepared full SHA를 포함한다.
• Gitea와 local에서 동일 tag가 존재하지 않는다.
• 동일 artifact version 또는 image tag가 존재하지 않는다.
• 필요한 credential과 target이 확인됐다.
• 필수 test와 check가 exact prepared commit에서 성공했다.
• Worktree HEAD와 tree가 준비 검증 이후 바뀌지 않았다.

하나라도 불명확하면 외부 상태를 변경하지 않는다.

6. Tag와 프로젝트별 게시

1. 승인된 exact tag를 prepared commit에 생성한다.
2. Explicit remote URL과 refspec으로 신규 tag만 non-force push한다.
3. Gitea readback으로 remote tag target이 prepared SHA와 일치하는지 확인한다.
4. Project release contract의 build, smoke test와 publish 절차를 그대로 실행한다.
5. 승인된 artifact와 immutable commit-derived tag만 게시한다.

latest, 추가 channel, 추정 artifact 또는 기존 tag를 게시·이동·덮어쓰지 않는다.

7. 권위 있는 검증

• Gitea remote tag target을 다시 읽는다.
• 게시 artifact의 version, digest 또는 checksum을 authoritative target에서 읽는다.
• Artifact provenance가 prepared SHA와 일치하는지 확인한다.
• 여러 tag를 게시했다면 모두 같은 승인 artifact를 가리키는지 확인한다.
• Gitea Release가 별도 승인됐다면 target, metadata와 attachments를 다시 읽는다.

완료 조건: remote tag와 모든 승인 산출물이 prepared SHA에 연결되고 immutable identifier로 확인된다.

8. 정리

모든 readback이 성공하고 worktree가 clean하며 prepared commit이 remote tag로 보존된 경우에만 release worktree를 제거한다.

1. Release lock과 repository lock을 유지한다.
2. Worktree lock을 해제하고 Git operation으로 registration과 checkout을 제거한다.
3. state.json과 빈 release directory만 제거한다.
4. Worktree와 registration 부재를 확인한 뒤 lock을 역순으로 해제한다.

Partial failure, dirty state, 미게시 commit 또는 불확실한 readback에서는 정리하지 않는다.

실패 처리

• Version, tag, commit, artifact 또는 target을 추측하지 않는다.
• 기존 tag를 force-update, 삭제 또는 재생성하지 않는다.
• 기존 artifact를 덮어쓰거나 삭제하지 않는다.
• 실패한 build를 임의 변경으로 수리하지 않는다.
• External write 실패를 blind retry하지 않는다.
• 부분 성공 상태와 안전한 재개 지점을 보존하고 사용자 결정을 요청한다.

검증 및 보고

완료 보고에는 다음을 포함한다.

• repository와 authenticated identity
• base, prepared와 remote tag full SHA
• exact version과 tag
• 변경 파일과 commit
• 실행한 test·build·smoke 명령의 실제 결과
• 게시 artifact의 exact 이름과 immutable digest 또는 checksum
• 수행한 외부 write와 authoritative readback
• worktree 정리 또는 보존 상태
• blocker와 partial failure

명령 성공만으로 릴리즈 완료를 주장하지 않는다. Remote tag와 모든 승인 산출물의 fresh readback이 일치할 때만 완료다.