# Releases API

## Release Endpoints

### List Releases

```
GET /api/v1/repos/{owner}/{repo}/releases
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |
| `draft` | boolean | Filter by draft status |
| `pre-release` | boolean | Filter by pre-release status |

```bash
# List all releases
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases" \
  -H "Authorization: token ${FORGEJO_PAT}"

# List only non-draft, non-prerelease
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases?draft=false&pre-release=false" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases?page=1&limit=10" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Create Release

```
POST /api/v1/repos/{owner}/{repo}/releases
```

**CreateReleaseOption:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tag_name` | string | **yes** | Tag name for the release |
| `target_commitish` | string | no | Branch or commit SHA to tag (defaults to default branch) |
| `name` | string | no | Release title |
| `body` | string | no | Release description (markdown) |
| `draft` | boolean | no | Mark as draft |
| `prerelease` | boolean | no | Mark as pre-release |
| `hide_archive_links` | boolean | no | Hide auto-generated archive download links |

```bash
# Create a release
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0",
    "target_commitish": "{branch_or_sha}",
    "name": "v1.0.0 - Initial Release",
    "body": "## Changes\n- Feature A\n- Feature B\n\n## Bug Fixes\n- Fix X",
    "draft": false,
    "prerelease": false
  }'

# Create a draft release
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v2.0.0-rc1",
    "name": "v2.0.0 Release Candidate 1",
    "body": "Pre-release for testing",
    "draft": true,
    "prerelease": true
  }'

# Create release with hidden archive links
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.1.0",
    "name": "v1.1.0",
    "body": "Patch release",
    "hide_archive_links": true
  }'
```

---

### Get Latest Release

```
GET /api/v1/repos/{owner}/{repo}/releases/latest
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/latest" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Get Release by Tag

```
GET /api/v1/repos/{owner}/{repo}/releases/tags/{tag}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/tags/{tag}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Get Release by ID

```
GET /api/v1/repos/{owner}/{repo}/releases/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Edit Release

```
PATCH /api/v1/repos/{owner}/{repo}/releases/{id}
```

```bash
# Update release body and name
curl -s -X PATCH "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "v1.0.0 - Updated Title",
    "body": "Updated release notes\n\n## Changes\n- Updated description"
  }'

# Publish a draft release
curl -s -X PATCH "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"draft": false}'
```

---

### Delete Release

```
DELETE /api/v1/repos/{owner}/{repo}/releases/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Delete Release by Tag

```
DELETE /api/v1/repos/{owner}/{repo}/releases/tags/{tag}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/tags/{tag}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Release Assets

### List Assets

```
GET /api/v1/repos/{owner}/{repo}/releases/{id}/assets
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Upload Asset

```
POST /api/v1/repos/{owner}/{repo}/releases/{id}/assets
```

Uses multipart form upload. The query parameter `name` sets the asset filename.

```bash
# Upload a binary asset
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets?name={asset_name}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -F "attachment=@./{asset_file}"

# Upload a tarball
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets?name={asset_name}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -F "attachment=@./{asset_file}"

# Upload a checksum file
curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets?name={filename}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -F "attachment=@{/path/to/file}"
```

---

### Get Asset

```
GET /api/v1/repos/{owner}/{repo}/releases/{id}/assets/{attachment_id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets/{asset_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Edit Asset

```
PATCH /api/v1/repos/{owner}/{repo}/releases/{id}/assets/{attachment_id}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets/{asset_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"name": "{asset_name}"}'
```

---

### Delete Asset

```
DELETE /api/v1/repos/{owner}/{repo}/releases/{id}/assets/{attachment_id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/{release_id}/assets/{asset_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Release Object

```json
{
  "id": 5,
  "tag_name": "v1.0.0",
  "target_commitish": "{branch_or_sha}",
  "name": "v1.0.0 - Initial Release",
  "body": "## Changes\n- Feature A",
  "url": "https://{FORGEJO_HOST}/api/v1/repos/{owner}/{repo}/releases/{release_id}",
  "html_url": "https://{FORGEJO_HOST}/{owner}/{repo}/releases/tag/{tag}",
  "tarball_url": "https://{FORGEJO_HOST}/{owner}/{repo}/archive/{tag}.tar.gz",
  "zipball_url": "https://{FORGEJO_HOST}/{owner}/{repo}/archive/{tag}.zip",
  "hide_archive_links": false,
  "draft": false,
  "prerelease": false,
  "created_at": "2024-03-15T10:00:00Z",
  "published_at": "2024-03-15T10:00:00Z",
  "author": {
    "login": "admin",
    "id": 1
  },
  "assets": [
    {
      "id": 12,
      "name": "{asset_name}",
      "size": 10485760,
      "download_count": 42,
      "created_at": "2024-03-15T10:05:00Z",
      "browser_download_url": "https://{FORGEJO_HOST}/{owner}/{repo}/releases/download/{tag}/myapp-linux-amd64"
    }
  ]
}
```

## Complete Workflow: Create Release with Assets

```bash
# 1. Create the release
RELEASE=$(curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0",
    "name": "v1.0.0",
    "body": "First stable release"
  }')

RELEASE_ID=$(echo "$RELEASE" | jq -r '.id')

# 2. Upload assets
for file in ./dist/*; do
  name=$(basename "$file")
  curl -s -X POST "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/releases/${RELEASE_ID}/assets?name=${name}" \
    -H "Authorization: token ${FORGEJO_PAT}" \
    -F "attachment=@${file}"
done

echo "Release created with ID: ${RELEASE_ID}"
```
