Readme CI

2025-11-07 15:29:04 +02:00
parent a19648aacc
commit 54e83b0af9
5 changed files with 469 additions and 4 deletions
--- a/.gitea/scripts/README-update-readme.md
+++ b/.gitea/scripts/README-update-readme.md
@@ -0,0 +1,147 @@
+# 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()`