k8s-agent-skills 1.2.0

package/skills/flux/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: flux
+description: Use when working with Flux CD — debugging live clusters, writing/auditing Flux resources, or asking Flux CD questions. Routes to 3 sub-skills depending on the task.
+---
+
+# Flux CD
+
+Skill router. Pick the right sub-skill based on what user is doing.
+
+## Which Sub-Skill?
+
+| User wants to... | Load skill | What it does |
+|---|---|---|
+| Debug a failing HelmRelease/Kustomization on a live cluster | `gitops-cluster-debug` | Inspects Flux resource status, controller logs, traces dependency chains on live K8s |
+| Write/understand Flux CRDs, generate YAML, ask what a concept means | `gitops-knowledge` | CRD schemas, YAML patterns, API versions, Flux concepts, FluxInstance/ResourceSet |
+| Audit a GitOps repo for best practices, deprecated APIs, security | `gitops-repo-audit` | Scans repo files, validates schemas, flags deprecated APIs, checks RBAC/secrets |
+
+## Two Domains
+
+**Cluster (live):** HelmRelease stuck, Kustomization failing, FluxInstance broken → `gitops-cluster-debug`
+
+**Repo (static):** Write new Flux YAML, understand CRD fields, audit existing repo → `gitops-knowledge` for reference, `gitops-repo-audit` for validation
+
+## Common Task Map
+
+| Task | Sub-skill |
+|---|---|
+| "Why is my HelmRelease failing?" | `gitops-cluster-debug` |
+| "Show me how to write a ResourceSet" | `gitops-knowledge` |
+| "Audit my GitOps repo" | `gitops-repo-audit` |
+| "What API version for Flux CRDs?" | `gitops-knowledge` |
+| "Check if my repo has deprecated APIs" | `gitops-repo-audit` |
+| "FluxInstance not ready" | `gitops-cluster-debug` |
+| "Explain OCI-based GitOps" | `gitops-knowledge` |
+| "Check HelmRelease valuesFrom refs" | `gitops-repo-audit` |
+| "Monitor reconciliation, set up alerts" | `gitops-knowledge` |

package/skills/gitea/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: gitea
+description: Use when working with Gitea — route to the correct sub-skill based on what the user needs: API automation, runner management, container registry, webhooks, or tea CLI.
+---
+
+# Gitea (v1.26) — Skill Router
+
+Pick the right sub-skill.
+
+## Which Sub-Skill?
+
+| User wants to... | Load skill |
+|---|---|
+| Hit REST API endpoints, manage tokens, automate via curl | `gitea-api` |
+| Configure gitea-runner, register/deploy runners, manage Actions | `gitea-runner` |
+| Push/pull OCI images, manage container registry, configure packages | `gitea-registry` |
+| Create/manage webhooks, verify payloads, handle events | `gitea-webhooks` |
+| Use `tea` CLI for issues/PRs/repos/releases | `gitea-tea` |
+
+## Quick Map
+
+| Task | Skill |
+|---|---|
+| "Create a token via API" | `gitea-api` |
+| "Deploy a runner on Kubernetes" | `gitea-runner` |
+| "Push a Docker image" | `gitea-registry` |
+| "Set up a webhook for CI" | `gitea-webhooks` |
+| "List my repos with tea" | `gitea-tea` |
+| "Delete a package version" | `gitea-api` |
+| "Register an ephemeral runner" | `gitea-runner` |
+| "Multi-arch build and push" | `gitea-registry` |
+| "Verify webhook HMAC signature" | `gitea-webhooks` |

package/skills/gitea-api/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: gitea-api
+description: Use when working with the Gitea REST API — authentication, token management, repository/issue/PR CRUD, package management, admin operations, and general API automation with curl.
+---
+
+# Gitea REST API (v1.26)
+
+Base: `https://gitea.example.com/api/v1`. Swagger: `https://gitea.example.com/api/swagger`. OpenAPI spec: `https://gitea.example.com/swagger.v1.json`.
+
+## Authentication
+
+| Method | Header / Param | Use Case |
+|--------|---------------|----------|
+| Token | `Authorization: token <token>` | API tokens from Settings > Applications |
+| Basic Auth | `-u username:password` | Creating tokens (`POST /users/:name/tokens`) |
+| OAuth2 Bearer | `Authorization: bearer <token>` | OAuth2 access tokens |
+| URL param | `?token=<token>` | Simple scripts |
+| SSH signatures | `Signature` header with SSH key | mTLS-style auth via SSH |
+
+2FA: add header `X-Gitea-OTP: 123456` with Basic Auth.
+
+## Token Scopes
+
+`"scopes": ["all"]` or fine-grained: `["repo", "write:repository", "read:user", "read:organization"]`. Create via UI or `POST /api/v1/users/{username}/tokens`.
+
+## Key Endpoints
+
+### Users & Auth
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/user` | Current user info |
+| GET | `/users/{username}` | Get user |
+| POST | `/users/{username}/tokens` | Create API token (Basic Auth required) |
+
+### Repositories
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/repos/{owner}/{repo}` | Get repository |
+| POST | `/repos/{owner}/{repo}` | Create repository |
+| POST | `/repos/{owner}/{repo}/mirrors` | Sync mirror |
+
+### Issues & Pull Requests
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/repos/{owner}/{repo}/issues` | Create issue |
+| GET | `/repos/{owner}/{repo}/issues` | List issues (filters: state, labels, created_by) |
+| POST | `/repos/{owner}/{repo}/pulls` | Create pull request |
+| GET | `/repos/{owner}/{repo}/pulls` | List PRs |
+
+### Organizations
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/orgs/{org}` | Get organization |
+| POST | `/orgs/{org}/teams` | Create team |
+
+### Admin
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/admin/users` | List users (supports sorting/filtering) |
+| POST | `/admin/users` | Create user |
+| POST | `/admin/hooks` | Create system/default webhook |
+| GET | `/admin/hooks?type=system\|default` | List admin webhooks |
+
+### Packages
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/packages/{owner}` | List packages |
+| DELETE | `/packages/{owner}/{type}/{name}/{version}` | Delete package version |
+
+## Examples
+
+```bash
+# Create an issue
+curl -X POST https://git.example.com/api/v1/repos/myorg/myrepo/issues \
+  -H "Authorization: token <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Bug", "body": "Description", "labels": [1, 2]}'
+
+# List PRs with filters
+curl "https://git.example.com/api/v1/repos/myorg/myrepo/pulls?state=open&sort=recentupdate" \
+  -H "Authorization: token <token>"
+
+# Create API token (Basic Auth required)
+curl -X POST https://git.example.com/api/v1/users/myuser/tokens \
+  -u myuser:mypassword \
+  -H "Content-Type: application/json" \
+  -d '{"name": "ci-token", "scopes": ["repo", "write:repository"]}'
+
+# Delete a package version
+curl -X DELETE "https://git.example.com/api/v1/packages/myorg/container/myapp/1.0.0" \
+  -H "Authorization: token <token>"
+```
+
+## Common Mistakes
+
+- **2FA users** — must pass `X-Gitea-OTP` header with Basic Auth when creating tokens
+- **Token as query param** — `?token=...` works but logs expose it. Prefer header.
+- **Package delete needs all segments** — owner, type, name, version. Missing one = 404.

package/skills/gitea-registry/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: gitea-registry
+description: Use when working with the Gitea container registry — OCI/Docker v2 API, push/pull images, multi-arch builds, package management via API, and configuration for supported package types.
+---
+
+# Gitea Container Registry (v1.26)
+
+OCI-compatible registry using Docker Registry API v2. Supports Docker images, Helm charts, and all OCI artifacts.
+
+## Auth
+
+```bash
+docker login git.example.com
+# Username: gitea username
+# Password: personal access token (NOT account password for 2FA users)
+```
+
+## Image Naming
+
+```
+{registry}/{owner}/{image}:{tag}
+```
+
+Examples: `git.example.com/testuser/myapp:latest`, `git.example.com/myorg/backend:v1.2.3`
+
+## Push / Pull
+
+```bash
+docker tag myapp:latest git.example.com/testuser/myapp:latest
+docker push git.example.com/testuser/myapp:latest
+
+docker pull git.example.com/testuser/myapp:latest
+```
+
+## Multi-Arch
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 \
+  -t git.example.com/testuser/myapp:latest --push .
+```
+
+## API
+
+```bash
+# List packages for owner
+curl -H "Authorization: token <token>" \
+  https://git.example.com/api/v1/packages/testuser
+
+# Delete package version
+curl -X DELETE -H "Authorization: token <token>" \
+  https://git.example.com/api/v1/packages/testuser/container/myapp/1.0.0
+```
+
+## Supported Package Types
+
+alpine, cargo, chef, composer, conan, conda, container, cran, debian, generic, go, helm, maven, npm, nuget, pub, pypi, rpm, rubygems, swift, vagrant, **terraform** (v1.26+).
+
+## Config
+
+```ini
+[packages]
+ENABLED = true
+LIMIT_SIZE_CONTAINER = -1  # No size limit for container images
+```
+
+## Common Mistakes
+
+- **Tag case** — Tags are case-insensitive. `image:Tag` and `image:tag` are the same image.
+- **Auth for 2FA users** — Always use a personal access token as password, not account password.
+- **Delete needs all segments** — REST delete endpoint requires owner, type, name, and version.
+- **Helm chart push** — Use `helm push` with OCI format: `helm push mychart-1.0.0.tgz oci://git.example.com/myorg`.

package/skills/gitea-runner/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: gitea-runner
+description: Use when configuring Gitea Actions runners — registration, deployment modes, Docker vs host mode, Talos/Kubernetes host-mode, ephemeral runners, and v1.26 Actions features.
+---
+
+# Gitea Runner (v1.0.6)
+
+Formerly `act_runner`. Renamed in v1.0.0 (May 2026). Binary: `gitea-runner`. Image: `gitea/runner`. Latest: **v1.0.6**.
+
+## Registration
+
+Tokens at instance/admin, org, or repo level in Settings > Actions > Runners.
+
+```bash
+# Interactive
+gitea-runner register
+
+# Non-interactive
+gitea-runner register --no-interactive \
+  --instance https://git.example.com \
+  --token <token> \
+  --name my-runner \
+  --labels ubuntu-latest:docker://node:20-bookworm
+
+# Ephemeral (single-job runner, then exits)
+gitea-runner register --no-interactive --ephemeral \
+  --instance https://git.example.com \
+  --token <token>
+```
+
+Token also via CLI: `gitea --config /etc/gitea/app.ini actions generate-runner-token`.
+
+## Running
+
+```bash
+gitea-runner daemon --config config.yaml
+```
+
+Generate default config: `gitea-runner generate-config > config.yaml`.
+
+## Labels Format
+
+```
+<label>:<scheme>://<image>
+```
+
+- `:host` suffix — runs step on host (no Docker required)
+- `:docker://image` — runs step in container
+- `ubuntu-latest:docker://node:20-bookworm` — label `ubuntu-latest` runs in `node:20-bookworm` container
+
+## Deployment Modes
+
+| Mode | Description | Docker Required |
+|------|-------------|----------------|
+| **Host** | Steps run directly on host process | No |
+| **Docker** | Steps in sibling containers via socket | Yes (`/var/run/docker.sock`) |
+| **DinD** | Rootless, own Docker daemon in container | Yes (privileged container) |
+
+### Kubernetes / Talos (Host Mode)
+
+Talos has no Docker socket. Must use host mode with `:host` labels:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gitea-runner
+  namespace: gitea
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: gitea-runner
+  template:
+    metadata:
+      labels:
+        app: gitea-runner
+    spec:
+      containers:
+        - name: runner
+          image: gitea/runner:latest
+          env:
+            - name: GITEA_INSTANCE_URL
+              value: https://git.example.com
+            - name: GITEA_RUNNER_REGISTRATION_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: runner-token
+                  key: token
+            - name: GITEA_RUNNER_LABELS
+              value: "ubuntu-latest:host"
+```
+
+Runner container must include tools its workflows need (curl, git, node, etc.).
+
+### Docker Mode
+
+```bash
+docker run -d \
+  -e GITEA_INSTANCE_URL=https://git.example.com \
+  -e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
+  -e GITEA_RUNNER_NAME=runner-1 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  gitea/runner:latest
+```
+
+## Ephemeral Runners
+
+Set `GITEA_RUNNER_EPHEMERAL=1`. Runner runs exactly one job then exits. Use `workflow_job` webhook to autoscale (spin up new runner per job).
+
+## v1.26 Actions Features
+
+- **Concurrency groups** — GitHub-style `concurrency:` in workflows
+- **Per-runner disable/pause** — toggle via UI, no unregister needed
+- **Rerun failed jobs** — button in UI
+- **Configurable token permissions** — `permissions:` block in workflows
+- **Non-zipped artifacts** — action v7 format
+- **Private repo workflows** — reusable workflows from private repos
+- **Workflow dependencies graph** — visual dependency tree in UI
+
+## Common Mistakes
+
+- **Stale image** — `gitea/act_runner` is deprecated. Use `gitea/runner`.
+- **No `:host` on Talos** — Without Docker socket, labels must use `:host` suffix. Runner will fail trying to spawn containers.
+- **Registration token via GET removed** — v1.26 removed `GET /api/v1/admin/runners/registration-token`. Use UI or `gitea actions generate-runner-token`.
+- **Cache config** — `cache.external_server` now requires `cache.external_secret` (v1.0.0+). Set both or cache fails.

package/skills/gitea-tea/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: gitea-tea
+description: Work with Gitea using tea CLI for auth, repo, issue, pull request, release, actions, webhook, and notification workflows. Use when user references Gitea, self-hosted git forges, or asks for tea commands.
+---
+
+# Gitea + tea CLI
+
+Use this skill when tasks target Gitea and the `tea` CLI, especially if the user would normally use `gh` on GitHub.
+
+## When To Use
+
+- User mentions Gitea, self-hosted git, forgejo-compatible flows, or `tea`
+- You need CLI automation for issues, pull requests, repos, comments, or releases
+- You need host-specific auth profiles (multiple Gitea instances)
+- Managing Gitea Actions (secrets, variables, runners, workflow runs)
+- Managing webhooks, notifications, or admin tasks
+
+## Core Rules
+
+1. Prefer `tea` over `gh` for Gitea targets.
+2. Always scope commands to target explicitly when ambiguity exists:
+   - `--repo owner/name`
+   - `--login <profile>`
+   - `--remote <remote-name>`
+3. If command flags differ by tea version, run `tea <cmd> --help` first and follow local help text.
+4. For PR/review actions, ensure local branches are pushed before create/merge operations.
+
+## Auth Workflow
+
+### Create login profile (token)
+
+```bash
+tea logins add --name <profile> --url https://git.kubexa.tech --token <token>
+```
+
+### Verify logins / switch default
+
+```bash
+tea logins ls
+tea logins default <profile>
+```
+
+### Quick auth check
+
+```bash
+tea whoami                         # Show current user
+```
+
+### Optional env-based auth (automation)
+
+- `GITEA_SERVER_URL`
+- `GITEA_SERVER_TOKEN`
+- `GITEA_SERVER_USER`
+- `GITEA_SERVER_PASSWORD`
+
+## Command Mapping (gh -> tea)
+
+- Repo list: `gh repo list` -> `tea repos ls`
+- Issue list: `gh issue list` -> `tea issues ls`
+- Issue create: `gh issue create` -> `tea issues create`
+- PR list: `gh pr list` -> `tea pulls ls` or `tea pr ls`
+- PR create: `gh pr create` -> `tea pulls create`
+- PR checkout: `gh pr checkout <n>` -> `tea pulls checkout <n>`
+- Comment on PR/issue: `gh pr comment` / `gh issue comment` -> `tea comment <index> [body]`
+- Release list/create: `gh release list/create` -> `tea releases ls` / `tea releases create`
+
+## Practical Patterns
+
+### Work on a specific repo
+
+```bash
+tea issues ls --repo owner/name --login <profile>
+tea pulls ls --repo owner/name --login <profile>
+```
+
+### Create issue / PR
+
+```bash
+tea issues create --repo owner/name --title "Title" --description "Details"
+tea pulls create --repo owner/name --head <branch> --title "Title" --description "Details"
+```
+
+### Review / merge PR
+
+```bash
+tea pulls review <index>
+tea pulls approve <index>
+tea pulls merge <index>
+```
+
+### Release workflow
+
+```bash
+tea releases create --repo owner/name --tag vX.Y.Z --title "vX.Y.Z"
+tea releases assets --help
+```
+
+### Clone repo
+
+```bash
+tea clone <repo-slug> [target-dir]
+tea clone gitea/tea                                 # Short form
+tea clone https://git.kubexa.tech/owner/repo.git    # Full URL
+```
+
+Supports various slug formats: `owner/repo`, `host/owner/repo`, full URLs. Overrides login when host specified.
+
+## Gitea Actions
+
+### Repository actions (secrets, variables, runs, workflows)
+
+```bash
+tea actions secrets ls --repo owner/name
+tea actions secrets create --repo owner/name <name> <value>
+
+tea actions variables ls --repo owner/name
+tea actions variables set --repo owner/name <key> <value>
+
+tea actions runs ls --repo owner/name
+tea actions runs view <run-id> --repo owner/name
+tea actions runs logs <run-id> --repo owner/name
+
+tea actions workflows ls --repo owner/name
+tea actions workflows dispatch <workflow-id> --repo owner/name
+tea actions workflows enable <workflow-id> --repo owner/name
+tea actions workflows disable <workflow-id> --repo owner/name
+```
+
+### Host-mode runner on Talos
+
+Talos has no Docker socket, so standard dind runners won't work. Use host-mode runner:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gitea-runner
+spec:
+  template:
+    spec:
+      containers:
+        - name: runner
+          image: gitea/runner:latest
+          env:
+            - name: GITEA_INSTANCE_URL
+              value: https://git.kubexa.tech
+            - name: GITEA_RUNNER_REGISTRATION_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: gitea-runner-token
+                  key: token
+            - name: GITEA_RUNNER_LABELS
+              value: "ubuntu-latest:host"    # Host mode = no Docker
+```
+
+- Label must include `:host` suffix for host-mode execution
+- Job steps run as processes inside the runner container
+- Runner container needs tools that workflows require (curl, git, etc.)
+- For Kubernetes-specific workflows, mount kubeconfig or use SA token
+
+## Notifications
+
+```bash
+tea notifications ls               # List unread + pinned (default)
+tea notifications ls --types issue,pull  # Filter by type
+tea notifications read <id>        # Mark as read
+tea notifications unread <id>      # Mark as unread
+```
+
+Defaults to current repo only. Use `--mine` for cross-repo notifications.
+
+## Webhooks
+
+```bash
+tea webhooks ls --repo owner/name
+tea webhooks create https://hook.example.com/endpoint --repo owner/name --type gitea --events push
+tea webhooks create --org my-org --type slack --events issues --secret <secret>
+tea webhooks delete <id> --repo owner/name
+```
+
+`--type` options: `gitea`, `gogs`, `slack`, `discord`, `dingtalk`, `telegram`, `msteams`, `feishu`, `wechatwork`, `packagist`. Default events: `push`. Supports `--org` (org-level hooks) and `--global` (instance-wide).
+
+## Admin
+
+```bash
+tea admin users ls                 # List registered users
+tea admin users list --login admin # Requires admin token
+```
+
+Only `users` subcommand currently. Requires login with admin privileges.
+
+## Safety + Verification
+
+- Run read-only commands first (`ls`, `list`, `view`) before mutating operations.
+- If repo context unclear, require explicit `--repo` and `--login`.
+- Before destructive actions (`delete`, `close`, `merge`), confirm target index and repository.
+- For actions: check workflow runs with `ls` before `cancel`/`delete`.
+- If command fails, capture `tea <subcommand> --help` output and adapt flags to installed version.
+
+## Troubleshooting
+
+- Auth failures: re-check login profile URL/token; verify `tea logins ls`.
+- Wrong target host/repo: pass both `--login` and `--repo` explicitly.
+- PR creation errors: ensure branch is pushed and upstream is configured.
+- TLS issues on internal hosts: prefer proper CA trust; use insecure flags only when user explicitly accepts risk.
+- Actions runner registration: pre-create the runner token in Gitea UI (Settings > Actions > Runners) or use API.

package/skills/gitea-webhooks/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: gitea-webhooks
+description: Use when managing Gitea webhooks — creating webhooks via API, understanding event types, system vs repo vs org webhooks, payload verification with HMAC-SHA256, and supported webhook formats.
+---
+
+# Gitea Webhooks (v1.26)
+
+## Events
+
+| Event | Trigger |
+|-------|---------|
+| `push` | Git push |
+| `create` / `delete` | Branch/tag created or deleted |
+| `fork` | Repo forked |
+| `issues` | Issue opened/closed/reopened/edited/deleted |
+| `issue_assign` | Issue assigned/unassigned |
+| `issue_label` | Issue labels updated |
+| `issue_comment` | Comment on issue |
+| `pull_request` | PR opened/closed/reopened/edited/synced |
+| `pull_request_review_approved` | PR approved |
+| `pull_request_review_rejected` | PR rejected |
+| `pull_request_review_comment` | PR review comment |
+| `pull_request_review_request` | Review requested |
+| `wiki` | Wiki edited |
+| `repository` | Repo created/deleted |
+| `release` | Release published/updated/deleted |
+| `package` | Package published |
+| `status` | Commit status updated |
+| `workflow_run` | Actions workflow run completed |
+| `workflow_job` | Actions workflow job ready (autoscaling trigger) |
+
+## API
+
+```bash
+# Create repo webhook
+curl -X POST https://git.example.com/api/v1/repos/{owner}/{repo}/hooks \
+  -H "Authorization: token <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "gitea",
+    "config": {
+      "url": "https://example.com/webhook",
+      "content_type": "json",
+      "secret": "my-secret"
+    },
+    "events": ["push", "pull_request"],
+    "active": true
+  }'
+
+# List webhooks
+curl https://git.example.com/api/v1/repos/{owner}/{repo}/hooks \
+  -H "Authorization: token <token>"
+
+# Delete webhook
+curl -X DELETE https://git.example.com/api/v1/repos/{owner}/{repo}/hooks/{id} \
+  -H "Authorization: token <token>"
+```
+
+## System vs Repo Webhooks
+
+| Type | Scope | API Endpoint |
+|------|-------|-------------|
+| Repository | Single repo | `POST /api/v1/repos/{owner}/{repo}/hooks` |
+| Organization | All repos in org | `POST /api/v1/orgs/{org}/hooks` |
+| System | All repos instance-wide | `POST /api/v1/admin/hooks` (`config.is_system_webhook: true`) |
+| Default | Template for new repos | `POST /api/v1/admin/hooks` (`config.is_system_webhook: false`) |
+
+## Payload Verification
+
+Gitea signs the raw request body with HMAC-SHA256 using the configured secret.
+
+**Header:** `X-Gitea-Signature`
+
+**Verify server-side:**
+```python
+import hmac, hashlib
+
+signature = request.headers.get("X-Gitea-Signature")
+expected = hmac.new(secret.encode(), request.body, hashlib.sha256).hexdigest()
+if not hmac.compare_digest(signature, expected):
+    abort(401)
+```
+
+## Webhook Types (format)
+
+`gitea` (generic JSON), `gogs`, `slack`, `discord`, `dingtalk`, `telegram`, `msteams`, `feishu`, `wechatwork`, `packagist`.
+
+## Common Mistakes
+
+- **HMAC algorithm** — Gitea uses SHA256, not SHA1. Check `X-Gitea-Signature` header.
+- **System webhook flag** — Must set `config.is_system_webhook` to `true` for instance-wide webhooks. Defaults to false (template webhook).
+- **Event names** — Use snake_case in API: `pull_request`, `issue_comment`. Verify against docs.
+- **workflow_job for autoscaling** — Use `workflow_job` event (not `workflow_run`) to trigger ephemeral runner spin-up.