148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
# 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
|
|
[](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** | [](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()`
|