# Package Linking Issue Diagnosis

## Current Status

✅ All 5 Docker images built and pushed successfully
❌ Package linking failed with 404 errors

## What I Found

### 1. Gitea Version

- **Current version:** 1.24.3
- **API added in:** 1.24.0
- **Status:** ✅ Version supports the package linking API

### 2. API Endpoint Format

According to [Gitea PR #33481](https://github.com/go-gitea/gitea/pull/33481), the correct format is:

```
POST /api/v1/packages/{owner}/{type}/{name}/-/link/{repo_name}
```

### 3. Our Current Implementation

```bash
POST https://git.mosaicstack.dev/api/v1/packages/mosaic/container/stack-api/-/link/stack
```

This matches the expected format! ✅

### 4. The Problem

All 5 package link attempts returned **404 Not Found**:

```
Warning: stack-api link returned 404
Warning: stack-web link returned 404
Warning: stack-postgres link returned 404
Warning: stack-openbao link returned 404
Warning: stack-orchestrator link returned 404
```

## Possible Causes

### A. Package Names Might Be Different

When we push `git.mosaicstack.dev/mosaic/stack-api:tag`, Gitea might store it with a different name:

- Could be: `mosaic/stack-api` (with owner prefix)
- Could be: URL encoded differently
- Could be: Using a different naming convention

### B. Package Type Might Be Wrong

- We're using `container` but maybe Gitea uses something else
- Check: `docker`, `oci`, or another type identifier

### C. Packages Not Visible to API

- Packages might exist but not be queryable via API
- Permission issue with the token

## Diagnostic Steps

### Step 1: Run the Diagnostic Script

I've created a comprehensive diagnostic script:

```bash
# Get your Gitea API token from:
# https://git.mosaicstack.dev/user/settings/applications

# Run the diagnostic
GITEA_TOKEN='your_token_here' ./diagnose-package-link.sh
```

This script will:

1. List all packages via API to see actual names
2. Test different endpoint formats
3. Show detailed status codes and responses
4. Provide analysis and next steps

### Step 2: Manual Verification via Web UI

1. Visit https://git.mosaicstack.dev/mosaic/-/packages
2. Find one of the stack-\* packages
3. Click on it to view details
4. Look for a "Link to repository" or "Settings" option
5. Try linking manually to verify the feature works

### Step 3: Check Package Name Format

Look at the URL when viewing a package in the UI:

- If URL is `/mosaic/-/packages/container/stack-api`, name is `stack-api` ✅
- If URL is `/mosaic/-/packages/container/mosaic%2Fstack-api`, name is `mosaic/stack-api`

## Next Actions

1. **Run diagnostic script** to get detailed information
2. **Check one package manually** via web UI to confirm linking works
3. **Update .woodpecker.yml** once we know the correct format
4. **Test fix** with a manual pipeline run

## Alternative Solution: Manual Linking

If the API doesn't work, we can:

1. Document the manual linking process
2. Create a one-time manual linking task
3. Wait for a Gitea update that fixes the API

But this should only be a last resort since the API should work in version 1.24.3.

## References

- [Gitea Issue #21062](https://github.com/go-gitea/gitea/issues/21062) - Original feature request
- [Gitea PR #33481](https://github.com/go-gitea/gitea/pull/33481) - Implementation (v1.24.0)
- [Gitea Issue #30598](https://github.com/go-gitea/gitea/issues/30598) - Related request
- [Gitea Packages Documentation](https://docs.gitea.com/usage/packages/overview)
- [Gitea Container Registry Documentation](https://docs.gitea.com/usage/packages/container)