# Auto-Update README Workflow

## Overview

This workflow automatically updates the `README.md` file with the current list of ArgoCD applications based on the directory structure in `k8s/`.

## How it works

1. **Trigger**: Workflow runs automatically when changes are pushed to `k8s/**` paths
2. **Scan**: Python script scans `k8s/` directory structure and finds all applications
3. **Generate**: Creates README.md with badges for all found applications
4. **Create PR**: If changes detected, creates a Merge Request for manual review

## Files

- `.gitea/workflows/update-readme.yaml` - GitHub Actions workflow
- `.gitea/scripts/generate-readme.py` - Python script for README generation

## Directory Structure

The script expects the following k8s directory structure:

```
k8s/
├── core/          # Core infrastructure applications
│   ├── argocd/
│   ├── authentik/
│   └── ...
├── apps/          # User applications
│   ├── gitea/
│   ├── immich/
│   └── ...
└── games/         # Game servers
    ├── minecraft/
    └── ...
```

Each subdirectory name becomes an application name in the README.

## Required Secrets

The workflow requires the following secrets to be configured in Gitea:

| Secret | Description | Example |
|--------|-------------|---------|
| `GT_URL` | Gitea instance URL | `https://gt.hexor.cy` |
| `GT_TOKEN` | Gitea API token with repo write access | `glpat-xxxxx...` |
| `GT_OWNER` | Repository owner (username or org) | `ab` |
| `GT_REPO` | Repository name | `homelab` |

### How to create a Gitea Token

1. Go to Settings → Applications → Generate New Token
2. Give it a name like "README Update Bot"
3. Select scopes: `repo` (Full control of repositories)
4. Generate and copy the token
5. Add it as a secret in repository settings

## Badge Format

Badges are generated using a predictable pattern:

```markdown
[![app-name](https://ag.hexor.cy/api/badge?name=app-name&revision=true)](https://ag.hexor.cy/applications/argocd/app-name)
```

This allows you to immediately see which applications are:
- ✅ Healthy and synced (green badge)
- ⚠️ Degraded or out of sync (yellow badge)
- ❌ Unhealthy or failed (red badge)

## Manual Trigger

You can manually trigger the workflow from Gitea:

1. Go to Actions tab
2. Select "Auto-update README" workflow
3. Click "Run workflow"
4. Select branch and run

## Example Output

The generated README will look like:

```markdown
# homelab

ArgoCD homelab project

## ArgoCD Applications Status

| Application | Status |
| :--- | :---: |
| **argocd** | [![argocd](https://ag.hexor.cy/api/badge?name=argocd&revision=true)](https://ag.hexor.cy/applications/argocd/argocd) |
...
```

## Reviewing Pull Requests

When the workflow creates a PR:

1. Check the Actions tab for the workflow run details
2. Review the PR in the Pull Requests tab
3. Verify the application list matches your k8s/ structure
4. Merge when ready

The PR will include:
- Updated application list
- Timestamp of generation
- Automatic commit message

## Troubleshooting

### No PR created

- Check if there are actually changes in README.md
- Verify secrets are configured correctly
- Check workflow logs in Actions tab

### Wrong applications listed

- Verify k8s/ directory structure
- Ensure folder names match expected application names
- Check for hidden directories (starting with `.`)

### Badge not loading

- Verify ArgoCD badge API is accessible at `https://ag.hexor.cy`
- Check application name matches ArgoCD application name
- Ensure application exists in ArgoCD

## Maintenance

### Update badge URL

If you need to change the badge URL pattern, edit:
- `.gitea/scripts/generate-readme.py` - function `generate_badge_line()`

### Change workflow trigger

To modify when the workflow runs, edit:
- `.gitea/workflows/update-readme.yaml` - `on:` section

### Add new categories

To add new categories (besides core/apps/games), edit:
- `.gitea/scripts/generate-readme.py` - function `scan_k8s_directory()` and `generate_readme_content()`