Initialize gitea-agent harness
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
---
|
||||
name: gitea-release
|
||||
description: 승인된 Gitea 버전을 준비·태깅하고 산출물을 게시한다.
|
||||
version: 0.1.0
|
||||
author: genichin, Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [gitea, release, worktree, tag, artifact]
|
||||
related_skills: [gitea-repository-cache-bootstrap]
|
||||
---
|
||||
|
||||
# Gitea Release
|
||||
|
||||
Gitea repository cache를 사용해 버전 준비, 검증, 태깅과 프로젝트별 산출물 게시를 수행한다. Cache 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)을 정본으로 사용한다.
|
||||
|
||||
## 사용 시점
|
||||
|
||||
- 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만 허용한다.
|
||||
|
||||
```text
|
||||
/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이 일치할 때만 완료다.
|
||||
Reference in New Issue
Block a user