CILocal.git · AGENTS.md

revision b91103012ecd5098ae0cb3826a0405dd8a90b314 · complete file

# Automation and Agent Guidelines

This document defines the standards and expectations for any agent (human or automated) interacting with the CI Control Plane repository. Adhering to these guidelines ensures that our local CI system remains reliable, secure and in sync with the Fountain Coach GitHub organisation.

## Source of truth

The **local Gitea instance**, orchestrated by the CI Control Plane, is the authoritative source of truth for all repositories in the Fountain Coach ecosystem. All work must be committed and pushed to Gitea first. Push mirrors to GitHub are configured to perform force pushes; changes made directly on GitHub will be overwritten on the next mirror cycle【853056115883648†L146-L165】. Do not open pull requests or commit directly on GitHub unless explicitly instructed.

## Spec‑driven development

1. **OpenAPI documents are mandatory.** Every HTTP surface in this repository—whether provided by FountainStore, a control plane API or a server extension—must have an OpenAPI specification. The spec is the single source of truth for the API shape【162382890305722†L0-L5】. Any change to an endpoint must be reflected in the OpenAPI doc **before** writing code.
2. **Regenerate clients:** After updating an OpenAPI spec, regenerate clients using Apple’s Swift OpenAPI Generator and commit the generated code. Regenerated code must be reviewed alongside the spec.
3. **Tests accompany changes:** All new behaviour must be covered by tests. FountainStore treats durability and correctness as non‑negotiable【4817992737384†L17-L33】; follow this ethos in the control plane. Run `swift test` and ensure coverage remains high.

## Secrets and credentials

1. **Never commit secrets:** API tokens, passwords and SSH keys must not be checked into version control. Instead, use Swift‑SecretStore to persist them locally. If you are on Linux, set the `KEYSTORE_PASSWORD` environment variable before storing secrets. On macOS, the Keychain backend is used automatically【668073400910452†L259-L283】.
2. **Environment variables:** When a secret cannot be retrieved from the secret store, the CLI falls back to environment variables. Use uppercase keys like `GITEA_ADMIN_TOKEN` or `JENKINS_API_TOKEN` only during development.
3. **Fine‑grained tokens:** When configuring mirrors to GitHub, generate a personal access token with the minimum required scopes and store it under a distinct key.

## Branching and commits

* Use feature branches for all changes. Merge into `main` only after tests pass and a code review is complete.
* Keep commits small and focused. Each commit message should describe what changed and why.
* Avoid introducing new dependencies without discussion. The project’s goal is to minimise third‑party dependencies; rely on pure Swift or standard CLI tools where possible.

## Contributor responsibilities

* **Audit logs:** When performing setup or mirroring operations, capture relevant output (e.g. generated tokens, repository names) and persist it in FountainStore. These logs should be retrievable via the control plane for auditing purposes.
* **Documentation:** Update `README.md` and `docs/OVERVIEW.md` when adding commands or changing workflows. Document any assumptions, environment variables or ports used.
* **Security:** Review dependencies for vulnerabilities and ensure that images pulled from external registries are from trusted sources. FountainStore emphasises durability and integrity【4817992737384†L17-L33】; treat the rest of the stack with similar care.

By following these guidelines you help maintain a robust local CI environment that mirrors gracefully to GitHub and supports the broader Fountain Coach ecosystem.