ab/homelab

Files

2025-11-07 15:29:04 +02:00

4.0 KiB

Raw Blame History

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

Trigger: Workflow runs automatically when changes are pushed to k8s/** paths
Scan: Python script scans k8s/ directory structure and finds all applications
Generate: Creates README.md with badges for all found applications
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

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

Badge Format

Badges are generated using a predictable pattern:

[![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:

Go to Actions tab
Select "Auto-update README" workflow
Click "Run workflow"
Select branch and run

Example Output

The generated README will look like:

# 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:

Check the Actions tab for the workflow run details
Review the PR in the Pull Requests tab
Verify the application list matches your k8s/ structure
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()

4.0 KiB Raw Blame History