Imported from Nilirad/commit-bridge (AGENTS.md). Install upstream with npx skills add Nilirad/commit-bridge. Copyright stays with the author.

Agent Instructions for commit-bridge

This file contains crucial context for AI agents working in this repository.

Development Commands

• Testing: Run cargo nextest run --locked --all-features (CI specifically uses nextest; prefer this over standard cargo test).
• Linting: Run cargo clippy --locked --all-targets --all-features -- -D warnings.
• Formatting: Run cargo fmt --all -- --check.
• SQLx Offline Mode: This project uses sqlx with offline query checking (evidenced by the .sqlx/ dir). Whenever you modify a database query, you must run cargo sqlx prepare -- --all-targets to update the cache.
• Migration Creation: Always use cargo sqlx migrate add <name> to generate new migrations. Manual creation of migration files is strictly prohibited to ensure proper tracking and naming conventions.
• Destructive Schema Changes: Dropping/renaming columns requires synchronization with sqlx cache.
  1. Remove code references (mark fields #[allow(dead_code)] if needed).
  2. Run cargo sqlx prepare.
  3. Apply ALTER TABLE ... DROP COLUMN migration.
  4. Cleanup removed fields/references.
  5. Run cargo sqlx prepare again.

Environment & Setup

• Nix First: The project uses Nix flakes (flake.nix) and direnv, and the Rust toolchain is only available inside the dev shell. In interactive shells, direnv loads it automatically; in non-interactive/automated shells the direnv hook does not run, so load the environment explicitly before any cargo invocation:

  • Run direnv allow once if the .envrc is blocked.
  • Run eval "$(direnv export bash 2>/dev/null)", then verify with command -v cargo (should print a /nix/store/... path).
  • If direnv is unavailable or cannot evaluate the envrc (e.g. restricted home access), fall back to nix develop -c <command>.

• Runtime Variables: To run the server locally, you must ensure CBRIDGE__AUTH__CLIENT_ID and CBRIDGE__AUTH__PEM_PATH are set (pointing to a valid GitHub App private key).

• External Dependencies: Remote git operations are performed in-process via the gix crate; the application no longer shells out to git ls-remote, so an external git binary is not required at runtime.

Architecture

• Frameworks: axum for HTTP, sqlx (SQLite) for state, tokio for async execution.
• Execution Flow: src/main.rs initializes an axum router and spawns two decoupled background tokio tasks:
  1. polling/: Periodically checks remote git repositories for updates.
  2. trigger/: Receives update events from the polling engine via mpsc channels and triggers GitHub Action workflows on target repositories.
• Error Handling: Use thiserror for domain-specific error enums, defined in the layer they belong to: HandlerError in src/http/error.rs, repository errors in src/repository/error.rs, engine errors in src/{polling,trigger}/error.rs, and value-validation errors in src/domain/. Boot-time errors (FatalError, SetupError) live in src/error.rs. Implement IntoResponse for any error that bubbles up to an Axum handler.

Reviews

When reviewing the correctness of code, always make sure that a potential issue can actually arise in the context of the affected piece of code.