QuantEngineByItz/docs/GITEA_ACTIONS_API_GUIDE.md

# Gitea Actions API 호출 가이드

**작성일**: 2026-07-11  
**대상**: QuantEngine CI/CD 담당자  
**목표**: CLI에서 Gitea Actions 상태 조회 및 troubleshooting

---

## 사전 요구사항

### 환경 변수 설정
```powershell
# PowerShell
$env:GITEA_TOKEN_TAXBAIK = "your_gitea_access_token"

# 또는 Windows 환경변수 저장
[Environment]::SetEnvironmentVariable("GITEA_TOKEN_TAXBAIK", "your_token", "User")
```

### 토큰 생성
1. Gitea 웹 UI: https://gitea.taxbaik.com/user/settings/applications
2. "Generate New Token" → 권한: `repo`, `read:actions`
3. 토큰 복사 및 환경 변수 설정

---

## API Endpoints

### 1. 최근 Workflow Runs 조회

```powershell
$token = $env:GITEA_TOKEN_TAXBAIK
$response = Invoke-WebRequest `
    -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs" `
    -Headers @{
        "Accept" = "application/json"
        "Authorization" = "token $token"
    }
$data = $response.Content | ConvertFrom-Json
$data.workflow_runs | ForEach-Object {
    Write-Host "Run #$($_.id): $($_.display_title) [$($_.status)/$($_.conclusion)]"
}
```

**Bash/cURL 버전:**
```bash
curl -X GET "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs" \
  -H "Accept: application/json" \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" | jq '.workflow_runs[] | {id, display_title, status, conclusion}'
```

---

### 2. 특정 Run 상세 정보 조회

```powershell
$run_id = 1987
$response = Invoke-WebRequest `
    -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs/$run_id" `
    -Headers @{
        "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK"
    }
$run = $response.Content | ConvertFrom-Json

Write-Host "Run #$($run.id)"
Write-Host "  Title: $($run.display_title)"
Write-Host "  Status: $($run.status)"
Write-Host "  Conclusion: $($run.conclusion)"
Write-Host "  Commit: $($run.head_sha)"
Write-Host "  Branch: $($run.head_branch)"
Write-Host "  Created: $($run.created_at)"
Write-Host "  Updated: $($run.updated_at)"
```

---

### 3. Run의 Jobs 조회

```powershell
$run_id = 1987
$response = Invoke-WebRequest `
    -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs/$run_id/jobs" `
    -Headers @{
        "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK"
    }
$jobs_data = $response.Content | ConvertFrom-Json

$jobs_data.jobs | ForEach-Object {
    Write-Host "Job #$($_.id): $($_.name)"
    Write-Host "  Status: $($_.status), Conclusion: $($_.conclusion)"
    Write-Host "  Started: $($_.started_at)"
    Write-Host "  Completed: $($_.completed_at)"
}
```

---

## Troubleshooting

### 문제: Run이 failure 상태

**원인 분석:**
```powershell
# 1. Jobs 상태 확인
$run_id = 1987
$response = Invoke-WebRequest `
    -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs/$run_id/jobs" `
    -Headers @{ "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK" }
$jobs = ($response.Content | ConvertFrom-Json).jobs

# 2. failure 상태인 job 찾기
$failed_jobs = $jobs | Where-Object { $_.conclusion -eq "failure" }
$failed_jobs | ForEach-Object {
    Write-Host "Failed Job: $($_.name) (ID: $($_.id))"
    Write-Host "  Status: $($_.status)"
}

# 3. Build 로그 확인 (로컬 또는 프로덕션 서버)
ssh kjh2064@178.104.200.7 'ls /opt/stacks/gitea/gitea/actions_log/kjh2064/taxbaik/*/*.log.zst'
```

### 문제: Act Runner 연결 실패

**증상:**
```
error="unavailable: dial tcp 172.18.0.2:3000: connect: connection refused"
```

**해결 방법:**
```bash
# 1. Runner 상태 확인
docker ps | grep runner

# 2. Runner 로그 확인
docker logs gitea-runner | grep -E "error|failed|connection" | tail -20

# 3. Gitea ↔ Runner 네트워크 확인
docker network ls
docker network inspect bridge | grep -E "Name|Containers"

# 4. Runner 재시작 (위험: 진행 중인 job 중단)
docker restart gitea-runner gitea-runner-2 gitea-runner-3
```

---

## 실행 예제

### 예제 1: 최근 Failed Run 찾기

```powershell
$response = Invoke-WebRequest `
    -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs?limit=10" `
    -Headers @{ "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK" }

($response.Content | ConvertFrom-Json).workflow_runs `
    | Where-Object { $_.conclusion -eq "failure" } `
    | ForEach-Object {
        Write-Host "❌ Run #$($_.id): $($_.display_title)"
        Write-Host "   Commit: $($_.head_sha.Substring(0, 7))"
        Write-Host "   Time: $($_.completed_at)"
    }
```

### 예제 2: Run 전체 Job 상태 맵

```powershell
function Show-RunStatus {
    param($RunId)
    
    $run_url = "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs/$RunId"
    $run = (Invoke-WebRequest -Uri $run_url -Headers @{ "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK" }).Content | ConvertFrom-Json
    
    Write-Host "Run #$RunId ($($run.display_title))" -ForegroundColor Cyan
    Write-Host "Status: $($run.status) / Conclusion: $($run.conclusion)"
    Write-Host ""
    
    $jobs_url = "$run_url/jobs"
    $jobs = (Invoke-WebRequest -Uri $jobs_url -Headers @{ "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK" }).Content | ConvertFrom-Json
    
    $jobs.jobs | ForEach-Object {
        $icon = if ($_.conclusion -eq "success") { "✓" } elseif ($_.conclusion -eq "failure") { "✗" } else { "⊘" }
        Write-Host "  [$icon] $($_.name) ($($_.status))"
    }
}

# 사용
Show-RunStatus -RunId 1987
```

---

## API 응답 구조

### Run Object
```json
{
  "id": 1987,
  "display_title": "CI: Trigger deploy-prod.yml workflow via git push",
  "head_sha": "5b41423aef4a03398f6b80c55c959563583e4f28",
  "head_branch": "main",
  "status": "completed",
  "conclusion": "failure",
  "created_at": "2026-07-11T22:33:06+09:00",
  "updated_at": "2026-07-11T22:33:34+09:00"
}
```

### Job Object
```json
{
  "id": 2375,
  "name": "Build Release",
  "status": "completed",
  "conclusion": "failure",
  "started_at": "2026-07-11T13:33:06+09:00",
  "completed_at": "2026-07-11T13:33:34+09:00"
}
```

---

## 자주 묻는 질문 (FAQ)

**Q: 토큰 권한이 부족하면?**
```
"message": "invalid username, password or token"
```
A: Gitea 설정에서 토큰 재생성, `repo` + `read:actions` 권한 부여

**Q: Run 로그를 API로 다운로드할 수 없나?**
A: 현재 Gitea API는 `/actions/runs/{id}/logs` 지원하지 않음. 프로덕션 서버에서 `/opt/stacks/gitea/gitea/actions_log/` 디렉토리 직접 접근

**Q: 가장 최신 Run 빠르게 확인하는 법?**
```powershell
$latest = ((Invoke-WebRequest -Uri "https://gitea.taxbaik.com/api/v1/repos/kjh2064/QuantEngineByItz/actions/runs?limit=1" `
  -Headers @{ "Authorization" = "token $env:GITEA_TOKEN_TAXBAIK" }).Content | ConvertFrom-Json).workflow_runs[0]
Write-Host "$($latest.display_title): $($latest.conclusion)"
```

---

## 관련 문서

- [CLAUDE.md - Deployment Gates](https://gitea.taxbaik.com/kjh2064/QuantEngineByItz/src/branch/main/CLAUDE.md)
- [deploy-prod.yml - 4-Stage Pipeline](.gitea/workflows/deploy-prod.yml)
- [Gitea Official API Docs](https://docs.gitea.io/en-us/api-usage/)

---

**마지막 업데이트**: 2026-07-11  
**상태**: 운영 중 - Act Runner 연결 불안정 이슈 진행 중