Guides

Practical how-to documentation for fullsend, organized by audience. For design documents and architectural context, see docs/problems/, docs/ADRs/, and docs/architecture.md.

Getting started

Guides for onboarding organizations and configuring GitHub or GitLab — the first thing most users need.

• Mint enrollment — Enroll your repo in a token mint before configuring anything else
• Getting Inference — Provision GCP inference access for your org or repo
• Configuring GitHub — Install GitHub Apps and run the setup CLI
• Configuring GitLab — Declare the project in repos.yaml, install with repos install, runners, polling, and role-credential lifecycle
• Repo Management — Manage many repositories from a declarative repos.yaml manifest
• Migrating to manifest-driven repos install — Move github setup installations and flag-driven repos install scripts to repos.yaml

Operations & Advanced Setup

Guides for organization owners and repository administrators who manage fullsend installations.

• Operations — Enrollment, configuration updates, status checks, uninstall, standalone commands, and private-CA GitLab trust
• Advanced setup — Alternative installation paths, setup flags, custom app sets, and manual WIF configuration
• OpenAI Workload Identity — Run GPT models on the pi runtime without a stored OpenAI key: console setup, repository variables, local runs, troubleshooting

Infrastructure

Advanced guides for platform operators who deploy and manage the GCP-side infrastructure (token mint, WIF, secrets).

• Mint service administration — Deploying and managing the token mint (GCP or Cloudflare)
• Standalone mint — Running the token mint as a standalone HTTP server without GCP
• Infrastructure reference — Token mint, WIF, and secrets deployment details
• Enabling fullsend on private repositories — Additional guardrails and configuration for private repos
• Gate binaries — Building statically linked binaries for custom endpoint access constraints beyond L4/L7 rules
• Tracing reference — Telemetry levels, environment variables, span hierarchy, and attributes
• Eval measurements — Online trace scoring with eval-measurements.jsonl and measurement manifests
• Inference gateway operator guide — Run an agentgateway inference gateway on Cloud Run that trusts GitHub Actions OIDC, for gateway/ models on pi, codex and Claude Code

User guides

Guides for developers working in repositories where fullsend is active.

• Adopting fullsend incrementally — Crawl, walk, run, fly: incremental adoption path from first agents to auto-merge
• How fullsend authenticates — Which credential path fullsend uses in each case: the mint, GCP and OpenAI Workload Identity, and the gateway's direct OIDC trust
• Using an inference gateway — Reach models through an OpenAI/Anthropic-compatible gateway with direct OIDC trust (no token exchange) or a gateway key
• Bugfix workflow — End-to-end guide to how fullsend handles a bug report from issue to merge
• Issue commands — Read, create, and post comments on issues across GitHub, GitLab, and Jira (fullsend issues get, create, post-comment)
• OWNERS file authorization — Authorize agent dispatch via Prow-style OWNERS files
• Running agents locally — Run fullsend agents on your machine using released binaries (macOS + Linux)

Customizing agents

Start with the overview to pick the right approach, then follow the relevant guide:

• Customizing agents overview — Quick decision guide for all customization approaches
• Configuring with AGENTS.md — Guide agents using your repo's AGENTS.md file
• Configuring with skills — Extend built-in agent skills; authoring augmentations
• Configuring agent behavior — Harness composition, status notifications, disabling agents, and GitHub Packages
• Bring Your Own Agent — Build and register a custom agent from scratch
• Custom Agent Identity — Using a standalone mint for custom GitHub App identity
• Chaining Follow-up Workflows — Act on an agent's result from your own workflow with the job token
• Harness Field Reference — Complete harness YAML field reference, merge rules, and resource referencing
• CEL Triggers Reference — Dispatch flow, NormalizedEvent fields, transition kinds, and trigger patterns
• Custom Poller Example — Create a custom poller workflow that invokes fullsend harness agents with a pre-computed matrix
• Building custom agents from scratch — (deprecated — see Bring Your Own Agent)
• Default, derived, and custom agents — When configuration crosses into derived or custom agent territory

Integrations & observability

• Jira Integration — Connect fullsend to a Jira project so that issue comments and label changes trigger agents
• How to emit traces — Configure a repository or organization to send OpenTelemetry traces to a remote backend
• Tracing with MLflow — MLflow-specific setup: experiment routing, Basic auth encoding, org-level organization, and cost column caveats

Development

Guides for contributors developing and testing fullsend itself.

• E2E testing — Local and CI e2e runs, including PR authorization and ok-to-test
• CLI internals — Command structure, installation pipeline, and sandbox runtime
• Behaviour testing — Write Gherkin scenarios for end-to-end agent behaviour
• Behaviour test drivers — Implement SCM and CI drivers for behaviour tests
• Testing workflow changes — Point a test repository at a branch to test workflow, action, and agent changes before release, and run the PR CI checks locally with make ci-local
• Tracing internals — How the distributed tracing implementation works and how to extend it