Add GitHub Copilot instructions and CI/CD conventions documentation

2026-07-12 09:23:07 +02:00
parent a8d44b320b
commit 7766091f73
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
 # GitHub Copilot Instructions
 This repository contains a small Go-based Traefik ForwardAuth service for `gitea-mcp` access control. Keep changes minimal, infrastructure-aware, and aligned with the deployment and CI conventions below.
 ## Project Purpose
 - This service validates `Authorization: Bearer <token>` for Traefik ForwardAuth.
 - The service is intentionally small and should prefer the Go standard library over additional frameworks.
 - Authentication is hash-only: the service stores and loads only SHA-256 token hashes, never plaintext tokens.
 ## Go and Build Conventions
 - Use Go `1.26` unless the repository is explicitly updated to a newer version.
 - Keep the module path aligned with the self-hosted Gitea instance: `gitea.nehmer.net/torben/gitea-mcp-forward-auth`.
 - Prefer standard library packages such as `net/http`, `log/slog`, and `crypto/subtle`.
 - Keep code testable: separate token validation logic from HTTP handler behavior.
 ## Security Requirements
 - Never log plaintext bearer tokens.
 - Only log a short token fingerprint or derived identifier that does not reveal the original token.
 - Token comparisons must remain constant-time.
 - Token configuration must stay hash-based:
  - `AUTH_PROXY_TOKEN_HASHES_DIR`
  - `AUTH_PROXY_TOKEN_HASHES`
 - Do not reintroduce plaintext token configuration or examples.
 - `/healthz` does not need to be world-readable. Prefer internal-only exposure for k3s probes and Prometheus.
 ## Kubernetes and Deployment Assumptions
 - Kubernetes manifests under `deploy/k3s/` are reference examples only.
 - Actual cluster deployment and rollout automation happen in a separate FluxCD repository.
 - Do not add FluxCD deployment logic to this repository unless explicitly requested.
 - Keep the Service internal (`ClusterIP`) unless the user explicitly asks otherwise.
 - NetworkPolicy changes must preserve the assumption that only trusted in-cluster components should reach this service.
 - If labels or namespaces for Traefik or Prometheus are assumed, mark them explicitly as assumptions in comments or docs.
 ## CI/CD Conventions
 - Gitea Actions are the target, not GitHub Actions cloud defaults.
 - Container build jobs must use:
  - `runs-on: container-builder`
  - `container.image: debian:trixie-slim`
 - If a workflow uses Node-based actions such as `actions/checkout` or `actions/setup-go`, install required tools first inside the runner container.
 - Prefer Debian Trixie package names and behavior when editing workflows.
 - The Go package registry is the self-hosted Gitea registry:
  - `https://gitea.nehmer.net/api/packages/torben/go`
 - Preserve `GOPROXY` usage with the Gitea registry first, then public fallback if already used by the repo.
 ## Container Release Conventions
 - Release images are published to `gitea.nehmer.net/torben`.
 - The image name is `gitea-mcp-auth-proxy` unless the user changes it explicitly.
 - Release builds use a remote BuildKit daemon, not a local Docker daemon.
 - Preserve the remote builder pattern:
  - determine host IP from the default route
  - connect to `tcp://$HOST_IP:1234`
 - Keep the 1Password secret-loading pattern for registry credentials.
 - Stable tags (`vX.Y.Z`) may publish `latest`; prerelease tags must not publish `latest`.
 ## Repo Hygiene
 - Ignore only the root build artifact `/authproxy`; do not ignore `cmd/authproxy`.
 - When changing workflows, prefer explicit artifact paths like `dist/...` over implicit binary output in the repo root.
 - Check `README.md` on updates and expand usage instructions where necessary. The file should be targeted for using the proxy, not for developing it.
 ## Documentation Style
 - Call out infrastructure-specific behavior as `Assumption:` when it depends on the user's environment.
 - Keep examples consistent with the current security model, especially hash-only token configuration.
 - Do not describe this repository as the deployment source of truth; it only builds the service and related reference manifests.