Config Reference
Complete reference for all fields available in .fullsend/config.yaml. For how these fields resolve through layered configuration, see Layered Config Reference. Fleet manifests can declare the same managed-configuration schema (every field below, including runtime and allowed_remote_resources) as defaults.config, github.config, gitlab.config, or per-repository config in repos.yaml (this is not config_base, which is the configuration-preset path written to .fullsend/config.base.yaml); see Repo Management — Managed configuration. trace_context is the exception: only a concrete repository entry may declare it. For initial setup, see Configuring GitHub or Configuring GitLab.
# ── Schema ───────────────────────────────────────────────────
version: "1" # Schema version (required)
# ── Platform ─────────────────────────────────────────────────
forge: github # Hosting platform: github, gitlab (auto-detected if omitted)
# ── Operations ───────────────────────────────────────────────
kill_switch: false # Emergency stop — disables all agent dispatch when true
keep_history: true # Append previous sticky-comment content as collapsed "Previous run" blocks
# ── Runtime ──────────────────────────────────────────────────
runtime: claude # Default agent runtime: claude, pi, codex, opencode
# ── Roles ────────────────────────────────────────────────────
roles: # Agent roles to install (determines which Apps and credentials are provisioned)
- triage
- coder
- review
- fix
- retro
- prioritize
# ── Agents ───────────────────────────────────────────────────
agents: # Registered agent sources and per-agent tuning
- source: https://example.com/triage.yaml#sha256=abc... # URL (requires #sha256=) or local path
name: triage # Explicit name (derived from source filename if omitted)
ref: main # Branch/tag resolved at adoption; used by `agent update`
enabled: true # Toggle agent on/off without removing the entry
runtime: claude # Per-agent runtime override
model: opus # Per-agent model override (model id or provider/id)
effort: high # Per-agent reasoning effort: low, medium, high, xhigh, max
subagents: # Per-agent sub-agent model map (pi and codex)
default: sonnet # Fallback model for personas without an explicit entry
code-reviewer: opus # Model for a specific persona
# trigger: <CEL expression> # When the built-in review agent runs (review entry only)
# harness: # Changes harness settings without a base: harness
# timeout_minutes: 90
# ── Remote resources ─────────────────────────────────────────
allowed_remote_resources: # URL prefixes allowed for remote resources (agents, policies, skills, plugins, profiles, providers, and base composition)
- https://raw.githubusercontent.com/fullsend-ai/fullsend/
- https://raw.githubusercontent.com/fullsend-ai/agents/
# ── Issue tracker ────────────────────────────────────────────
tracker: # Issue tracker. At most one provider block: github, gitlab, or jira
github:
allowed_targets:
orgs: # GitHub orgs agents may create issues in
- my-org
repos: # Specific repos (owner/name) agents may create issues in
- fullsend-ai/fullsend
- fullsend-ai/agents
# gitlab:
# allowed_targets:
# groups: [my-group] # GitLab groups (projects in the group and its subgroups)
# repos: [my-group/sub/project] # Full project paths
# jira:
# base_url: https://example.atlassian.net # Jira site URL (required with any Jira setting below)
# api_url: https://api.atlassian.com # Jira API gateway URL (optional; this is the default)
# project: PROJ # This repository's Jira project key (required with base_url)
# allowed_targets:
# projects: [OTHER] # Jira project keys for cross-project issue creation or moves
# poll:
# enabled: true # Managed poll workflow switch (see the tracker.jira section)
# query: 'labels = "fullsend" ORDER BY updated DESC' # JQL; always scoped to project
# ── Authorization ────────────────────────────────────────────
authorization: # Extra sources of permission for triggering agents
- provider: owners_file # GitHub: grant access from the repo-root Prow OWNERS file, checked before the collaborator API
- provider: jira # Jira (jira-poll): who may trigger agents from Jira events
write: # Fullsend role write
groups: [example-team-developers] # Jira group names (or group IDs)
accounts: ["5f7c012e0b2a4c001f3d9876"] # Jira account IDs
triage: # Fullsend role triage
groups: [example-team]
accounts: []
labels: jira_editors # Label-added events: jira_editors (default), allowlist, project_roles
# ── Status notifications ─────────────────────────────────────
status_notifications:
comment:
start: enabled # Post a comment when an agent starts: enabled (default), disabled
completion: enabled # Post a comment when an agent completes: enabled (default), on_failure, disabled
reaction:
start: disabled # Add an emoji reaction on start: enabled, disabled (default)
completion: disabled # Add an emoji reaction on completion: enabled, on_failure, disabled (default)
# ── Mint ─────────────────────────────────────────────────────
mint_url: https://mint.fullsend.sh # Token mint URL for credential issuance
# ── Inference ────────────────────────────────────────────────
inference:
provider: vertex # Inference backend: vertex
project: my-gcp-project # GCP project ID (must be provided by installer)
region: global # GCP region for inference requests
wif_provider: projects/123/locations/global/workloadIdentityPools/pool/providers/prov # WIF provider resource name
wif_audience: "" # GitLab: agent job ID token audience for an existing provider (default "fullsend")
service_account: "" # GitLab: service account email the agent job impersonates (default none)
openai: # OpenAI Workload Identity Federation (ADR 0092)
audience: "" # OpenAI WIF audience
identity_provider_id: "" # OpenAI WIF identity provider ID
service_account_id: "" # OpenAI WIF service account ID
gateway: # Inference gateway credential route (ADR 0137)
url: "" # Gateway URL, e.g. https://gateway.example.com or https://gateway.example.com/team-a (optional path prefix, no trailing /v1, port 443 only; plain http only for a loopback test host)
audience: "" # OIDC audience the runner requests for the gateway (oidc mode)
auth: "" # Credential mode: oidc (default) or api-key (ADR 0138)
messages_auth_header: "" # Messages-dialect credential header: authorization (default) or x-api-key (api-key mode only, ADR 0142)
models: {} # Inline model list: id -> {api, compat, contextWindow, maxTokens}
models_file: "" # Or: repository path to a pi-inference-gateway config file
# ── Model aliases ────────────────────────────────────────────
models:
aliases: # Override fullsend's pinned model alias table per key
opus: claude-opus-4-6 # Model id or provider/id spec
sonnet: claude-sonnet-5
haiku: claude-haiku-3-5
fable: claude-fable-5-1
# ── Runner secret sources (ADR 0155) ─────────────────────────
connections: # Named connections to secret services
vault: # Arbitrary alias; "native" is reserved
kind: vault # Required; v1 supports only vault
vault_address: https://vault.example.com # Required, HTTPS Vault API base URL
vault_namespace: "" # Optional Vault Enterprise namespace
vault_auth_path: jwt # JWT auth mount path, without auth/ (default jwt)
vault_role: fullsend-runner # JWT role (default fullsend-runner)
vault_audience: https://fullsend.sh/vault # Job OIDC token audience (default)
secrets: # Source selection for eligible runner secrets
JIRA_TOKEN:
connection: vault # A connections entry, or native (default when omitted)
vault_secrets: # Ordered KV v2 read paths, relative to /v1/
- kv/data/fullsend/repositories/{{repo.host}}/{{repo.full_name}}/jira
- kv/data/fullsend/organizations/{{repo.host}}/{{org}}/shared/jira
# ── Run artifacts ────────────────────────────────────────────
artifacts:
content: all # Every run: all (default) | metadata | none
by_source: # Per run source (event.source.system); stricter level wins
jira: metadata # e.g. runs started from a Jira issue
# ── Live progress log ────────────────────────────────────────
progress:
verbosity: full # Every run: full (default) | tools | quiet
by_source: # Per run source (event.source.system); stricter level wins
jira: quiet # e.g. runs started from a Jira issue
# ── Trace context ────────────────────────────────────────────
trace_context: # Trace-context keys of this repository (ADR 0154)
installation_id: 0f1e2d3c4b5a69788796a5b4c3d2e1f0 # 32 lowercase hex characters, not all zero
signing_key:
secret: FULLSEND_TRACE_SIGNING_KEY # Secret holding the private key; the only accepted value
verification_keys:
active: <public key> # Standard base64 of the 32-byte Ed25519 public key
retained: [<public key>] # Earlier public keys that still verifyField details
Most fields are self-explanatory from the inline comments above. This section expands on fields where additional context helps.
version
Schema version string. Must be "1". Present in every config file.
forge
Hosting platform for the repository (github or gitlab). When omitted, fullsend auto-detects the forge from CI environment variables. Most installations do not need to set this explicitly.
kill_switch
Emergency stop. When set to true, all agent dispatch is disabled for the repository. Uses pointer semantics in the layered config system — nil (omitted) falls through to parent; an explicit false is a local decision that does not fall through.
keep_history
Controls whether sticky comment updates (from post-review, post-comment, and issues post-comment) append the previous comment body as a collapsed "Previous run" <details> block. Default is true (history appended). Set to false when accumulated "Previous run" blocks add unwanted noise — for example, when comments are synced to Jira where <details> does not render as collapsible.
runtime
Default agent runtime for all agents in this repository. Valid values: claude, pi, codex, opencode. opencode is opt-in and limited to read-only agents (triage, prioritize) until the security-hook adapter lands (#7824). Per-agent overrides in the agents: list take precedence. Per-run overrides via --runtime flag or FULLSEND_RUNTIME env var take precedence over both. See Choose a Runtime for runtime comparison.
roles
Agent roles determine which GitHub Apps (and their associated credentials and permissions) are provisioned for the repository. Valid roles: fullsend, triage, coder, review, fix, retro, prioritize, e2e. The fix role reuses the coder GitHub App and PEM, so no separate App or secret is created for it. For each role's GitHub App and purpose, see Custom Agent Identity — Built-in roles.
Mint-only dogfood roles such as scribe can be registered with fullsend mint add-role (and used via remote harness registration) but are not valid values for roles until scaffold and workflow wiring lands. Adding them under roles fails config validation rather than silently no-oping.
In the layered config system, roles uses replace-if-set semantics — an overlay that sets roles replaces the parent list entirely (no union). Omitting the key inherits the parent's roles. See Layered Config Reference.
agents
Registered agent sources and per-agent tuning. Each entry identifies an agent by source URL or local path, with optional overrides for runtime, model, effort, sub-agent models, the trigger and harness settings.
source— URL (must include#sha256=<64-hex-char>integrity hash) or local path. URL sources must be covered byallowed_remote_resources.name— Explicit name. When omitted, derived from the source filename (e.g.,triage.yaml→triage). Must start with an alphanumeric character and contain only[a-zA-Z0-9_-].ref— Branch or tag resolved when the agent was adopted viafullsend agent add. When present,fullsend agent updatere-resolves against this ref. Empty for SHA-pinned or legacy entries.enabled— Toggle the agent without removing its entry. A suppression-only entry (enabled: false, no source) disables a built-in or parent-layer agent by name.runtime,model,effort— Per-agent overrides. An override-only entry (no source, at least one setting) tunes a built-in agent by name.subagents— Map of persona names to model references. Thedefaultkey sets the fallback for personas without an explicit entry. A~(null) value tombstones an inherited entry. Keys must be lowercase alphanumeric segments joined by hyphens (max 64 chars). On codex, for an agent that delegates, the values must be OpenAI ids and a key must name a registered persona ordefault; see Codex › Child models.trigger— A CEL trigger (a boolean over the normalizedevent). It decides routing for the built-in review, retro, triage and prioritize agents only: on one of those entries it opts the repository into CEL routing for that agent, so the trigger, not the dispatch workflow's built-in rules, decides when the agent's job starts (see Choosing when review runs, Choosing when retro runs and Choosing when triage and prioritize run). It does not change CEL dispatch: the harnesstrigger:keeps deciding when custom agents run and what the Jira poller dispatches. A trigger alone makes a valid override-only entry for a built-in agent. Validated when the agent list is validated: it must compile and return a boolean. Like an invalidmodeloreffort, an invalidtriggermakes every agent run in the repository fail withinvalid agent config, not only built-in routing, so check the expression before you merge the change.harness— A partial harness composed on the agent's harness as a child layer, as if it named that harness inbase:, with nothing pinned (ADR 0162). It changes harness settings without abase:harness, so the agent keeps getting agent updates. It merges by thebase:composition rules of the harness field reference. A scalar replaces the harness value. A list adds to it. Eachenvvariable replaces the harness value, and~sets it empty.yamlagents: - name: review harness: env: runner: { REVIEW_FINDING_SEVERITY_THRESHOLD: medium } sandbox: { REVIEW_FINDING_SEVERITY_THRESHOLD: medium } - name: code harness: timeout_minutes: 90 env: runner: { GITHUB_SIGNED_COMMITS: "true" } sandbox: { TIMEOUT_SECONDS: "5400" } - name: fix harness: env: runner: { GITHUB_SIGNED_COMMITS: "true" }GITHUB_SIGNED_COMMITS: "true"turns on signed commits for the code and fix agents on GitHub. The post-script publishes the agent's commits through the Git Data API, and GitHub signs them (see Signed commits).TIMEOUT_SECONDSistimeout_minutesin seconds. The code, fix and review skills read their time limit from it, so change both together.- Fields. The block takes every harness field except
base,forgeandrunner_env; an overlay in the block cannot setrunner_enveither. An unknown key fails. So does a value that no harness accepts, such as an unknowneffort. envnames. The block cannot add a variable. A name that the agent's harness does not declare in that section fails. The error names the agent and the variable. A name counts as declared when any layer of the harness sets it at top level, in aforge:block or in an overlay. A name fullsend reserves in the sandbox fails in either section. Adding a variable still takes abase:harness.schema_version. Absent means1. A block whose version differs from the agent's harness fails to load (ADR 0127).- Runtime fetch. Like a
base:child, the block does not inheritallowed_remote_resources,allow_runtime_fetchormax_runtime_fetches.fullsend lintwarns when a block leaves out one that the harness or theconfig.base.yamlblock sets. The warning names the field. To keep it, set it in the block. When both files have a block, set it in theconfig.yamlone. To drop the fields on purpose, setallow_runtime_fetch: falsein the block; lint then does not warn. allow_ci_variable_credential. The block does not inherit this field either.fullsend lintwarns when a block leaves it out and the harness or theconfig.base.yamlblock sets it totrue. To keep it, set it in the block. When both files have a block, set it in theconfig.yamlone. To drop it on purpose, set it tofalsein the block; lint then does not warn. Only GitLab runs read the field, so lint does not warn when the forge is known and is not GitLab.- Paths. Relative paths in the block resolve against the
.fullsenddirectory, like a local harness file's, and a path that escapes it is rejected. - Layers. The
config.base.yamlblock composes first, then theconfig.yamlblock, soconfig.yamlcan replace a value fromconfig.base.yamlbut not remove it. An entry inconfig.yamlwith no block, an empty one or a null one keeps theconfig.base.yamlblock. Inrepos.yaml, only one of thedefaults, forge and repositoryconfiglayers may set an agent's block, since they render into oneconfig.yaml. A repository pinned to afullsend_reffrom before blocks cannot take one:repos installfails that repository and names the entry (see Configuration schema of a pinned ref). - Fields the entry already has. Setting
model,effortortriggerboth on the entry and in the block fails, checked on the entry merged from both files. The built-in agents arereview,retro,triage,prioritize,codeandfix, whether or not the entry has asource. On a built-in agent, aharness.triggeris not evaluated. The configuration loads with a warning that names the agent. The entry'striggerkeeps deciding routing as described above. This lasts until built-in agents are routed by CEL alone (#2902). - Who reads it.
fullsend run,fullsend lint,fullsend lockand dispatch, CEL dispatch and the Jira poller included, all compose the block. A change to it makes the agent's lock entry stale.fullsend lockcomposes the block on the entry's harness only. It locks a localharness/<name>.yamlthat the entry does not name without the block, becausefullsend rundoes not use that file for the entry. A non-empty block alone makes a valid override-only entry. On a disabled entry the block is not composed. It is still validated when the entry has asource.
- Fields. The block takes every harness field except
In the layered config system, agents use keyed merge by DerivedName() — see Layered Config Reference.
For agent registration and management, see fullsend agent and Bring Your Own Agent.
allowed_remote_resources
URL prefixes allowed for remote resources in harness files — agent sources (agents: entries with URLs), policies, skills, plugins, profiles, providers, and base: composition. The config-level list acts as a fallback for all URL resolution: a URL is accepted if it matches either the harness-level or the config-level list. Default prefixes cover the fullsend and agents repositories. The same config-level list is also the ceiling for harness-level allowed_remote_resources: whenever a harness's runtime fetch service can start (allow_runtime_fetch: true, URL-sourced skill or plugin directories, or a bare, deprecated allowed_remote_resources declaration), every harness-level prefix must be covered by the config-level list (the built-in default prefixes are included when the list is omitted or non-empty; an explicit allowed_remote_resources: [] stays deny-all and cannot cover a harness prefix), and fullsend run, fullsend lint and fullsend lock fail naming the uncovered entry, and fail closed when no repository config (config.yaml or config.base.yaml) exists.
When the GITHUB_SERVER_URL environment variable names a GitHub host other than github.com (for example a GitHub Enterprise Server), the defaults also include the raw-content prefixes for the same two repositories on that host: https://<host>/fullsend-ai/fullsend/raw/ and https://<host>/fullsend-ai/agents/raw/. GitHub Actions sets this variable on every runner. No other path on that host is added.
In the layered config system, this field uses union-with-deny-all semantics: omitted inherits from parent; explicit empty ([]) denies all remote resources; a non-empty list is unioned with the parent's list. See Layered Config Reference.
That is the accessor-level value. Commands resolve one step further: the run/lint/lock family, harness dispatch, dispatch --route, the Jira poll and the agent-editing commands (agent set/add/update/remove) all resolve the list through EffectiveAllowedResources, which ensures fullsend's default prefixes on top of a non-empty result, so a first-party agent source covered only by a default prefix resolves with no configuration. perRepoConfig.Validate validates agents against the same effective list, so github setup re-runs and repos install admit the same shapes as the commands above; config_base preset validation parses the preset standalone (preset list plus the defaults, no overlay), so it is stricter than the read for overlay-only prefixes and for a preset [], and looser over a runtime overlay []; and managed repos.yaml validation (ValidateMergedManaged) checks merged managed agents against it too. A resolved empty list (an explicit []) stays deny-all. The rendered effective config (EffectiveYAML) shows the accessor-level list, which may omit the ensured defaults.
tracker
The issue tracker, as a single provider-discriminated mapping. tracker holds at most one provider block — github, gitlab, or jira — and the block that is present selects the provider. It is the default backend for the --tracker flag of fullsend issues commands (distinct from forge: a repository hosted on GitHub may track issues in Jira), and its allowed_targets restrict where agents may create issues. Declare a provider with no extra targets as an empty block (for example tracker: {jira: {}}). When omitted, no provider is selected, --tracker is required on every fullsend issues invocation, and agents cannot create issues outside the repository they run in. Validation rejects a tracker mapping with more than one provider block. See Jira Integration for cross-platform setup.
tracker.github.allowed_targets.orgs— GitHub organizations. All repos in these orgs are allowed.tracker.github.allowed_targets.repos— Specific repos in exactlyowner/nameformat.tracker.gitlab.allowed_targets.groups— GitLab groups (full group path). Projects in the group and its subgroups are allowed.tracker.gitlab.allowed_targets.repos— Specific projects by full project path (for examplegroup/subgroup/project).tracker.jira.allowed_targets.projects— Jira project keys (an uppercase letter followed by uppercase letters, digits, or underscores).
tracker.jira connection and polling settings
tracker.jira also holds the Jira site, project, and poller settings. The mapping can be set in .fullsend/config.yaml or in a repository's managed config: block in repos.yaml:
tracker:
jira:
base_url: https://example.atlassian.net
api_url: https://api.atlassian.com
project: PROJ
allowed_targets:
projects: [OTHER]
poll:
enabled: true
query: 'labels = "fullsend" AND statusCategory != Done ORDER BY updated DESC'tracker.jira.base_url— The Jira site URL. It must be anhttpsURL with no credentials, query, or fragment. It has no default. Whenfullsend runmints the sandbox's Jira token from OAuth 2.0 client credentials, setbase_urlandproject: the run looks up this site's cloud ID and limits thejiraprovider to it, and fails before minting without them. See Read-only Jira access from the sandbox.tracker.jira.api_url— The Jira API gateway URL. It is optional and defaults tohttps://api.atlassian.com. It is validated likebase_url. Fullsend's shared Jira client sends REST requests to{api_url}/ex/jira/{cloudId}/rest/api/3/.... It discovers the cloud ID from{base_url}/_edge/tenant_infoand keepsbase_urlfor issue browse links. An override must serve the same gateway path layout. The Jira poller (fullsend poll --input-driver jira-poll),fullsend issues, run-status updates, andfullsend reconcile-statusall use this client.api_urlholds only the gateway host. It is not the same as theJIRA_API_URLvariable thatfullsend runsets for Jira-sourced agent runs. That variable is the full per-site base{api_url}/ex/jira/{cloudId}that agents append/rest/api/3/...to. For those runsfullsend runalso setsJIRA_BASE_URLtobase_url. See Jira connection variables in agent runs. Whenfullsend runmints the sandbox's Jira token, leaveapi_urlunset or set it tohttps://api.atlassian.com. Any other value makes the run fail before minting, because thejiraprovider allows only that gateway.tracker.jira.project— The key of the single Jira project for this repository. It is not a fallback project, and it has no default.tracker.jira.run_label— Optional label added to the source Jira issue when any Jira-sourced agent run starts, before sandbox setup. Default: empty (disabled, with a skip log). Use a nonempty name without whitespace or control characters, for examplefs-code-agent; no product-branded label is supplied. Configuration validation rejects invalid names. At runtime, an invalid name produces a warning and skips labeling without blocking Jira runs or polling. Existing labels are preserved, and an issue that already has the label is not updated. This runs independently of status-comment settings. API failures warn without failing the run. The label remains after cancellation or failure. Choose a name that does not collide with your poll query's trigger/exclusion labels. See Tracking runs in Jira.tracker.jira.poll.enabled— Controls the managed poll workflow.trueinstalls or enables it,falseremoves or disables it. Whenpollorpoll.enabledis omitted, the workflow is not installed.fullsend poll --input-driver jira-pollalso reads it: unless it istrue, the poller skips the cycle without contacting Jira, and writes an empty dispatch list to--outputwhen that flag is set. It does not affectfullsend issues.fullsend repos installconverges it. When it istrue, install writes the Jira credentials from--jira-tokenand--jira-email, or the OAuth client ID and secret, and ensures the managed poll resources. When it isfalseor omitted, install removes those resources and keeps the credentials. On GitHub, install manages.github/workflows/fullsend-poll-jira.yml. On GitLab, it manages thefullsend jira pollpipeline schedule. See Jira polling.tracker.jira.poll.query— The JQL the poller runs. It defaults tostatusCategory != Done ORDER BY updated DESC. The query is always scoped toproject: the poller runsproject = "<project>" AND (<query>)and keeps a trailingORDER BYafter the closing parenthesis. The parentheses in the query must be balanced. For example, the query above runs asproject = "PROJ" AND (labels = "fullsend" AND statusCategory != Done) ORDER BY updated DESC.
base_url and project are required once base_url, api_url, project, a nonempty run_label, or poll is set. A mapping that only selects Jira (jira: {}) or only sets allowed_targets stays valid. This includes a mapping migrated from the legacy scalar tracker: jira.
Credentials are never part of this mapping. Keys such as token, api_token, email, password, client_id, or client_secret are rejected. Supply either a Jira token and optional account email as the FULLSEND_JIRA_TOKEN and FULLSEND_JIRA_EMAIL repository secrets, or an Atlassian service account's OAuth 2.0 client ID and secret as FULLSEND_JIRA_CLIENT_ID and FULLSEND_JIRA_CLIENT_SECRET. These credential sets are mutually exclusive. The shared Jira client treats the token as a scoped API token. When FULLSEND_JIRA_EMAIL is set, the client uses Basic auth with that email and a scoped user token (a bot user). When it is absent, the client sends the token as a Bearer token from a scoped service account. The token string does not show its type, so the email alone selects the mode. An Atlassian service account can use an OAuth 2.0 credential instead of a token. Supply it as the FULLSEND_JIRA_CLIENT_ID and FULLSEND_JIRA_CLIENT_SECRET repository secrets, and leave FULLSEND_JIRA_TOKEN and FULLSEND_JIRA_EMAIL unset. Setting both credential types, or only one of the client ID and secret, is an error. The client exchanges the credential with the client_credentials grant at https://auth.atlassian.com/oauth/token. It sends the resulting Bearer access token to the same api_url gateway and refreshes it before it expires. Other unknown keys under tracker.jira, tracker.jira.poll, and tracker.jira.allowed_targets are rejected too.
fullsend poll --input-driver jira-poll reads the Jira site, API gateway, project, and query only from the effective tracker.jira config, so it requires base_url and project. The removed --jira-url, --jira-project, and --jql flags are rejected, and environment variables such as JIRA_BASE_URL are not read. The poller authenticates with the shared Jira client: FULLSEND_JIRA_TOKEN is required and FULLSEND_JIRA_EMAIL is optional, or FULLSEND_JIRA_CLIENT_ID and FULLSEND_JIRA_CLIENT_SECRET replace both, as described above. The legacy JIRA_TOKEN and JIRA_USER_EMAIL variables are not used by the poller.
The fullsend issues commands (get, create, post-comment, link, transition), fullsend run Jira status updates, and fullsend reconcile-status read the Jira connection only from these settings, with no flag or environment fallback: base_url and project must be set, and Jira API calls fail without them. project is the default --project of the issues commands. fullsend issues create and fullsend issues transition refuse any other Jira project unless it is listed in allowed_targets.projects. See Issue commands.
For GitHub and GitLab the scopes are additive: a destination is allowed if it matches a configured org or group, or a configured repo. Malformed entries are rejected: an empty org or group, an org containing /, a GitHub repo not in owner/name form, a GitLab path with empty segments or a repo without a namespace, or an invalid Jira project key.
The repository agents run in is always allowed, so it does not need an entry. The default GitHub per-repo configuration generated without a preset lists both fullsend-ai/fullsend and fullsend-ai/agents in tracker.github.allowed_targets.repos, so retro proposals and triage prerequisites can reach the platform or agent repository that owns the change. These are installation defaults, not an automatic grant for every repository in allowed_remote_resources. Fresh GitLab installations instead record an explicit empty tracker.gitlab.allowed_targets policy: cross-project targets must be configured for the GitLab host. Explicit settings are preserved. Retro and triage post-scripts currently read only the overlay (.fullsend/config.yaml), not the preset (.fullsend/config.base.yaml). Until agents#1728 is fixed, preset users must declare the required config.tracker.<provider>.allowed_targets in the managed repository’s repos.yaml entry and rerun fullsend repos install, or edit .fullsend/config.yaml for an unmanaged installation. Updating only the preset does not enable these cross-repository operations. Include all targets the post-scripts need in the overlay policy. Existing installations retain their permissions on upgrade; on GitHub, to opt in, add fullsend-ai/agents to the existing target list in the managed repository’s repos.yaml configuration, or in .fullsend/config.yaml for an installation not managed through fullsend repos. Preserve any other targets you need.
In the layered config system, tracker replaces the parent's whole object when set, so layers never combine two providers. See Layered Config Reference.
Breaking change — migration from the scalar tracker: tracker used to be a scalar (tracker: jira). A scalar value is no longer accepted: validation (fullsend lint and CLI config writes) and config loading reject it with a migration message. A repos.yaml managed config: block containing it is converted by fullsend repos install (see below). Replace it with the provider block:
# before
tracker: jira
# after
tracker:
jira: {}Migration from create_issues: the top-level create_issues key is removed. Runtime config loading fails with a migration error when either .fullsend/config.yaml or .fullsend/config.base.yaml still contains create_issues; the key is never silently ignored. Validation also rejects it. Move create_issues.allow_targets.orgs and repos to tracker.github.allowed_targets.orgs and repos on GitHub, to tracker.gitlab.allowed_targets.groups and repos on GitLab, or to tracker.jira.allowed_targets.projects on Jira, and keep only one provider block.
Automatic migration of managed configuration: fullsend repos install converts the legacy scalar tracker and create_issues keys in repos.yaml managed config: blocks (defaults.config, the forge section's config, and each repository entry's config) before the manifest is decoded, writes the converted manifest, and re-renders each fullsend-managed .fullsend/config.yaml from it. Each layer that set a legacy key gets the full tracker mapping that was in effect there, because the legacy keys were inherited separately while a tracker mapping replaces the parent's. The effective provider and targets of every repository stay the same:
- A layer with no provider uses the repository's forge (
githuborgitlab). Acreate_issuesblock indefaults.configwith no provider is moved to each forge section'sconfig, becausedefaults.configapplies to both forges. - GitHub
orgsandreposstay organization and repository grants undertracker.github.allowed_targets. GitLabreposmove totracker.gitlab.allowed_targets.repos. - Install stops before any write, naming the manifest path and the edit to make, when a target has no unambiguous equivalent. That covers repository or organization targets under a Jira provider (Jira targets are project keys under
tracker.jira.allowed_targets.projectsand are never derived from repository paths), organization targets on GitLab (list the groups undertracker.gitlab.allowed_targets.groups), and a layer that combines atrackermapping withcreate_issues. - A scalar
trackerwith nocreate_issuesin the manifest becomes a provider block with noallowed_targets. As atrackermapping it replaces anytrackermapping in the preset (.fullsend/config.base.yaml).
Running install again changes nothing. A read-only or HTTPS manifest is converted in memory for that run and install prints the edits to apply to its source. --dry-run reports the conversion without writing. Markerless .fullsend/config.yaml files and presets are not converted; edit them by hand.
authorization
Lists extra sources of permission for triggering agents. There are two providers: owners_file for GitHub events and jira for Jira events.
owners_file
The GitHub collaborator API always applies; this provider is checked first:
- An
approversentry in the repo-rootOWNERSfile gets write-level access (every slash command and custom agent). Areviewersentry gets triage-level access, which covers/fs-triage,/fs-review, and custom agents whose harness setsrole: triageorrole: review. Custom agents with any otherrole:still require write. - An entry that names a key in
OWNERS_ALIASESstands for that alias's members. A GitHub login equal to any alias key never matches, and nested aliases are not expanded. - A user not found in
OWNERSfalls through to the collaborator API. - If
OWNERSorOWNERS_ALIASEScannot be parsed, or two alias keys differ only by case, the OWNERS check is skipped and only the collaborator API decides. - Only the flat root
approvers/reviewerslists are read. Prowfilters:blocks and per-directoryOWNERSfiles are ignored.
jira
Decides which Jira users may trigger agents through the jira-poll input driver. It applies only to events from Jira and does not change GitHub or GitLab authorization (ADR 0153).
| Key | Meaning |
|---|---|
write.groups, write.accounts | Jira groups (by name or group ID) and Jira account IDs granted the fullsend write role |
triage.groups, triage.accounts | Jira groups and account IDs granted the fullsend triage role |
labels | How a label-added event is authorized: jira_editors (default once the entry is present), allowlist, or project_roles |
- Slash commands and other non-label events: when the entry sets a
writeortriagelist (an empty list counts as set, so it denies everyone), the lists decide. An actor listed underwritegetswrite. An actor listed only undertriagegetstriage, which covers/fs-triageand custom agents whose harness setsrole: triageorrole: review. Anyone else is denied. The Jira project roles are not consulted. When neither list is set, slash commands use the Jira project role lookup instead. That lookup needs Administer Projects. Other non-label events, such as an issue being opened or edited, are then not authorized for any agent, unless the entry setslabels: project_roles: with that value and no lists, every event (labels, slash commands, opened, edited, closed, reopened, plain comments, label removals) resolves through the project role lookup, exactly as with nojiraentry. - Label-added events:
jira_editorsauthorizes anyone who could add the label, which needs Jira's Edit Issues permission.allowlistchecks the label author against the same lists as slash commands.project_rolesuses the Jira project role lookup. - Group entries are resolved with Jira's user-groups API, once per actor per poll cycle. That needs the poller account to hold the Browse users and groups global permission. Account entries need no Jira call. Project-role resolution calls the same API for an actor when a project role is granted to a group.
To keep today's behavior explicitly, use the two-line entry - provider: jira with labels: project_roles and no lists.
The provider is opt-in. Without a jira entry, every Jira event, including label-added events, resolves through the project role lookup and takes the per-harness role threshold, which needs Administer Projects. Unknown keys in a jira entry, an unknown labels value, and empty group or account entries fail config loading. See Jira integration for the permissions each setting needs.
Default: absent (owners_file off; Jira resolves every event through the project role lookup). The field is not inherited from config.base.yaml: each repo opts in in its own config.yaml. Unknown or duplicate providers fail config validation, and also fail jira-poll and harness dispatch at load time, and write, triage, and labels are valid only on the jira provider. See OWNERS file authorization for an owners_file setup walkthrough.
status_notifications
Controls the comments and reactions fullsend posts on issues and PRs when agents start and complete.
comment.start—enabled(default) ordisabled.comment.completion—enabled(default),on_failure(comment only on failure), ordisabled.reaction.start—enabledordisabled(default). Reactions are an opt-in alternative that does not generate a GitHub notification.reaction.completion—enabled,on_failure, ordisabled(default).
When status_notifications is omitted entirely, both start and completion comments default to enabled.
Completion comments. comment.completion decides whether a comment is posted when the run ends:
| Value | Behavior |
|---|---|
enabled | Always post a completion comment (default) |
on_failure | Post when the agent fails, is cancelled, or is skipped by a pre-script; the start comment is automatically suppressed to avoid notification noise |
disabled | Never post a completion comment; silently remove the start comment |
on_failure reduces notification noise: successful runs leave no trace, but failures still surface. With on_failure, the start comment is suppressed regardless of comment.start, because posting and then deleting a start comment would still trigger a GitHub notification pointing to a deleted comment.
In enabled mode, a hard crash or cancellation that happens before the agent could post anything at all is also surfaced after the fact: a post-job cleanup step synthesizes an "Interrupted" comment so the run doesn't silently vanish.
If workflow setup fails before the agent process starts, the dispatch workflow posts a separate "Fullsend agent did not run" comment with the failure category and workflow-run link. This startup-failure comment is emitted only for GitHub-originated events. Pre-agent failures from Jira- and GitLab-originated events are currently not reported by this fallback; tracker-specific startup-failure reporting is tracked in #9256. Retries of the same workflow run update the existing startup-failure comment instead of creating duplicates. A later workflow run normally posts a new comment so the historical failure and its workflow-run link are preserved; a later successful run does not remove that historical comment. Harness-dispatch failures are the exception: because they can recur on every forwarded event before any agent is selected, they update one stable comment per issue or PR with neutral wording that agents may not have run.
The standalone prioritize workflow also supplies the status target and, for GitHub-originated calls targeting a different repository, mints a prioritize-scoped GitHub token only for the startup-failure reporter. Same-repository calls use the workflow token and non-GitHub calls do not mint this reporting token. The normal github_token input remains the workflow token for installation, cloning, provider credentials, and fullsend run. This enables the same startup-failure reporting for cross-repository prioritize calls; if minting fails and the target is a different repository, the workflow emits an explicit warning because the caller's GITHUB_TOKEN cannot write to that repository.
Because this fallback runs specifically when the Fullsend CLI may not have been installed, it uses the workflow's GitHub comment API directly and does not read status_notifications. Therefore, a startup-failure comment can still be posted when status comments are disabled; this is intentional because the comment reports that the requested agent did not run at all.
When the startup-failure fallback has successfully posted, the action skips orphaned-status reconciliation. No Fullsend run was started in that case, so there is no start comment to reconcile; skipping it also prevents a second, misleading "Interrupted" comment. Other status side effects are consequently not run for that pre-agent failure.
Reactions. Emoji reactions don't generate a GitHub notification, so they are a lower-noise way to show that an agent is working and how the run turned out. Unlike comments, they default to disabled. When reaction.start is enabled, a 👀 reaction is added when the agent begins. At completion, the start reaction (if any) is removed and, depending on reaction.completion, replaced with an outcome reaction:
| Value | Behavior |
|---|---|
enabled | Always add a completion reaction: 👍 on success, 😕 on failure/cancelled/skipped |
on_failure | Add a 😕 reaction only on failure/cancelled/skipped; leave no reaction on success |
disabled | Never add a completion reaction (default) |
👎 is deliberately avoided for failures: it overloads GitHub's native up/down-vote convention, so a routine agent failure could be misread as the bot disliking the issue. Because reactions carry no notification cost, on_failure here only means "leave no reaction on success", with no start-suppression workaround.
For runs triggered by an issue or PR event, the reaction is added to the issue or PR itself. For runs triggered by a slash command comment (for example /fs-fix), it is added to the triggering comment instead, so it's clear which command the reaction is responding to.
Known limitations:
- Reactions are currently GitHub-only. Enabling
reaction.*on a GitLab-backed repo is silently a no-op today (#5998). - If a run is hard-killed before it can post its completion reaction, the start reaction (👀) can be left behind indefinitely. Unlike status comments, there's no out-of-process reconciler for orphaned reactions yet.
mint_url
Token mint URL for credential issuance. The mint service issues short-lived credentials to agents based on their role. Default: https://mint.fullsend.sh (the hosted public mint). Custom mint deployments set this to their own URL. See Standalone Mint and Mint Administration.
The URL must use https. Plain http is accepted only for localhost or 127.0.0.1, for a mint that runs on the same machine as the CLI or runner, such as in a test. A URL with userinfo (user:pass@) is rejected.
For GitHub repositories managed with fullsend repos install, a mint_url declared in the managed configuration (config.mint_url in repos.yaml) or the config_base preset also sets the FULLSEND_MINT_URL repository variable. Install, dry run and repos status report a conflict when it differs from the manifest's own mint_url. See Effective infrastructure values.
inference
Groups inference backend settings under a single key. Each subfield resolves independently through the layered config system (an overlay can override project without restating provider).
For repositories managed with fullsend repos install, project, region and wif_provider in the managed configuration or config_base preset feed the installed credentials: a declared region manages the FULLSEND_GCP_REGION variable for vertex-wif and openai-wif repositories (with none declared, an existing variable is kept and global is written only where it is missing), and project / wif_provider are written to the FULLSEND_GCP_PROJECT_ID / FULLSEND_GCP_WIF_PROVIDER secrets unless --vertex-project / --vertex-wif-provider supply them (a disagreeing flag is an error). See Effective infrastructure values.
provider— Inference backend identifier. Currently onlyvertex. Default:vertex.project— GCP project ID for inference requests. No default — must be provided by the installer or an existing secret.region— GCP region for inference. Default:global.wif_provider— Full Workload Identity Federation provider resource name. No default — must be provided by the installer.wif_audience— GitLabvertex-wifonly. The audience the GitLab agent job requests for its ID token (FULLSEND_ID_TOKEN), for an existing WIF provider that does not acceptfullsend.fullsend repos installrenders it into.gitlab/ci/fullsend-agent.yml. Default: unset, which keepsaud: "fullsend". Must be a single line of printable ASCII with no surrounding spaces and no$.service_account— GitLabvertex-wifonly. The email of a service account the agent job impersonates after the federated token exchange (<name>@<project>.iam.gserviceaccount.com).fullsend repos installwrites it as theFULLSEND_GCP_SERVICE_ACCOUNTCI/CD variable. Default: unset, which keeps direct federated identity.Both keys require an explicitly supplied
wif_provider(or--vertex-wif-provider) and are read only at install time. Inrepos.yaml, set them undergitlab.configor ongitlab.reposentries:github.configandgithub.reposentries reject them, and values inherited fromdefaults.configare ignored on GitHub repositories and on GitLab repositories that do not usevertex-wif. See Using an existing WIF provider.openai— OpenAI Workload Identity Federation identifiers (ADR 0092). TheFULLSEND_OPENAI_*runner variables, when set, replace the resolved block entirely. All three fields must come from one source for a run.fullsend repos installchecks the same sources for repositories whoseinference.authisopenai-wif. See OpenAI Workload Identity.gateway— a self-hosted, OpenAI/Anthropic-compatible inference gateway that validates the job's forge OIDC token directly (ADR 0137). Models with thegateway/prefix use this route. The block applies when it is complete and, in the defaultoidcmode, the run has a forge OIDC endpoint (a GitHub Actions job withid-token: write); theapi-keymode (seeauthbelow) has no such condition. In theoidcmode the runner then fetches the job's OIDC assertion foraudienceand puts it behind a run-scoped OpenShell provider with a per-host egress profile. It seeds the provider's placeholder into a runner-owned token file, and re-seeds it before each token's ownexp. OpenShell's placeholders do not say which rotation they belong to. So if the runner does not see a refreshed token's placeholder in the sandbox (the 90-second settle wait runs out, or reading it fails), it does not rotate again. It moves the provider's expiry back to the token the agent holds and stops refreshing, and the run fails closed when that token expires. The re-seed runs only after the sandbox hands out the new placeholder, and it checks the file afterwards. This happens in addition to every other provider:openai/and Vertex models in the same run keep their own routes. If the gateway cannot be reached, or refuses the token, the run fails and does not fall back to another credential. With no block, or in theoidcmode on a local run without an OIDC endpoint, the runner adds nothing on pi, so a harness that loads the inference-gateway extension as a plugin keeps working. codex and Claude Code have no such setup, so there agateway/model without a block that applies is an error. codex sendsgateway/models to the gateway'sPOST /v1/responsesthrough a runner-ownedfullsend-gatewayprovider (Codex › Models through an inference gateway). On Claude Code the runner exportsurlasANTHROPIC_BASE_URLand passes the id aftergateway/to--model; the model list is not used (details). Fields:url— the gateway origin, for examplehttps://gateway.example.com, optionally followed by the path prefix the gateway serves its API under, for examplehttps://gateway.example.com/team-afor a gateway behind a shared ingress. Must behttps(plainhttponly for a loopback test host), with no credentials, query or fragment, and no port other than 443: the runner adds the/v1/...model API paths itself, and the egress profile allows the gateway host on port 443 only. A path prefix must be a clean absolute path: no empty (//),.or..segment, no percent-encoding, only letters, digits,-,.,_and~in each segment, and no trailing/v1(writehttps://gateway.example.com/team-a, not.../team-a/v1). A trailing/is ignored. The prefix applies everywhere the runner builds a model API path: each runtime calls<url>/v1/..., the egress profile binds the credential to<prefix>/v1/**only (never the whole host) and allows only the model API paths under it, andfullsend inference gateway statusprobes<url>/v1/models. A bare origin works as before. The run route accepts a gateway on a private address, butfullsend inference gateway statusrefuses loopback, private and other internal addresses, so it cannot check one. For such a gateway, a run is the check: its first gateway model call fails if the gateway is unreachable or refuses the token.audience— the OIDC audience the runner requests. The token is valid only at the gateway. Required in theoidcmode; not used in theapi-keymode.auth— the credential mode,oidc(the default) orapi-key(ADR 0138). New in fullsend v0.47.0: an older CLI or reusable workflow rejects a config that sets it. There is no precedence and no fallback between them.oidcis the route described above.api-keyis for gateways that cannot trust forge OIDC. It is supported, but it is not the primary or safest option, because it relies on a long-lived secret: use it with caution, and preferoidcwhen the gateway supports it. In theapi-keymode the runner reads the gateway key from theFULLSEND_INFERENCE_GATEWAY_API_KEYforge secret or local environment variable, and fails the run when it is not set. It puts the key behind the same run-scoped provider placeholder, egress profile and guards as the OIDC token. The key is not rotated, so nothing is re-seeded. The block applies on local runs too, so the runner owns the route there as well. Forfullsend repos install, a complete block satisfies theinference.authrequirement. Theoidcmode is rejected for a gateway-only GitLab repository, and theapi-keymode needsFULLSEND_INFERENCE_GATEWAY_API_KEYset in advance (a masked, protected CI/CD variable on GitLab). See Inference gateway route.messages_auth_header— the header the gateway credential travels in on Messages-dialect requests:authorization(the default, used when the field is absent) orx-api-key(ADR 0142). A CLI or reusable workflow from v0.48.0 or earlier ignores the field and sendsAuthorization: Bearer, so anx-api-keygateway answers 401. Setx-api-keyfor a gateway that reads the caller's key fromx-api-keyon/v1/messages, the header Anthropic documents for API keys on that API. It is valid only withauth: api-key: a resolved block in theoidcmode that setsx-api-keyis a config error, because an OIDC token is a bearer token. Only the Messages dialect moves: pianthropic-messagesmodels send the key asx-api-key, and Claude Code gets it asANTHROPIC_API_KEYinstead ofANTHROPIC_AUTH_TOKEN. piopenai-responsesandopenai-completionsmodels, and codex, keepAuthorization: Bearer. Each request carries the credential in one header only. The header is configured, never guessed: the runner does not retry in the other header after a 401. A gateway that readsx-api-keymust remove the caller's key before it sets its own upstream key; see Header custody for an x-api-key gateway.models— optional inline model list, a map of model id to settings:api(one ofopenai-responses,anthropic-messages,openai-completions), and optionalcompat,contextWindowandmaxTokens.compatholds pi request-feature flags: each value is a boolean, string or number, a flag that pi-inference-gateway v0.1.1 knows must have that flag's type for the model'sapi, list-valued flags such asallowedFallbackModelsare refused, and an unknown flag whose name looks like a credential or header is refused.models_file— optional repository path, for example.fullsend/inference-gateway.json, to a file in the pi-inference-gateway config format. It must hold exactly one entry,providers.gateway, carrying onlymodels,include,excludeanddefaultApi, and every model must set its ownapi: pi runs offline, and the extension offers a configured model only when its entry names anapi. Per-model values follow the extension's types:compatas for inline models,contextWindowandmaxTokenspositive whole numbers,costonlyinput,output,cacheReadandcacheWriteas non-negative numbers, andthinkingLevelMapthinking levels mapped to a string ornull. Duplicate JSON keys are refused. These checks validate the file's shape; they are not secret detection.fullsend github setupcommits the file as written, so keep credentials out of free-text values such as model names.include,excludeanddefaultApionly apply to models discovered from the gateway, so they have no effect on a pi run. A file that setsbaseUrl,baseUrlEnv, a credential key (apiKey*,tokenFile,username*,password*),headers,authHeader,modelsPath,discoveryorfallbackModelsis refused: the runner owns those. The runner reads the file from the repository checkout thatconfig.yamlcame from, so it is read at the same ref (the base branch on pull-request events), even when an org or managed layer set the path.
urlis always required, and in theoidcmodeurlandaudienceare all or none:fullsend github setuprefuses to leave a block without them, and the runner fails a run whose resolved block is partial.modelsandmodels_fileare mutually exclusive. A pi run on agateway/model needs one of them, because pi runs offline and cannot discover the gateway's models. On codex the list is not used: fullsend renders no catalog for codex, so the id aftergateway/is the model it sends (a configuredmodels_filemust still be readable).url,audience,authandmessages_auth_headerlayer independently; the model list (either form) is one unit, and a layer that sets it replaces the inherited list. There is no runner-variable override for this block.fullsend github setup --inference-gateway-*writes it and changes only the keys you pass, so a repository can add its models under aurlandaudienceinherited fromconfig.base.yaml. For a walkthrough, see Using an inference gateway.
For setup instructions, see Getting Inference.
models
Model configuration, currently containing only aliases.
aliases— Per-key overrides of fullsend's pinned model alias table (defaults:opus→claude-opus-5-5,sonnet→claude-sonnet-5-5,haiku→claude-haiku-5-5, each with a built-in fallback chain to the previous default when the Vertex project does not serve it;fable→claude-fable-5-1on pi). An overridden alias has no built-in fallback chain. See Claude Code and pi. Keys are alias names (opus,sonnet,haiku,fable); values are model ids orprovider/idspecs (e.g.,claude-opus-4-6,google-vertex/gemini-3.8-flash). An unknown key is a validation error. A value must not be another alias name — aliases resolve once, sosonnet: opuswould reach the provider as the literal id "opus". In the layered config system, aliases merge per key across layers. See Layered Config Reference.
connections
Named connections to secret services that runner secrets can select (ADR 0155). Each key is an arbitrary alias of letters, digits, _, ., and -. native is a reserved built-in name and cannot be declared.
kind— Required. The only supported value isvault. A missing or unknown kind is a validation error.vault_address— Required forkind: vault. The Vault API base URL. It must usehttpsand must not contain user information, a query, or a fragment.vault_namespace— Optional Vault Enterprise namespace, sent asX-Vault-Namespace.vault_auth_path— JWT auth method mount path, without theauth/prefix. Defaults tojwt.vault_role— JWT auth role. Defaults tofullsend-runner.vault_audience— Audience of the job OIDC token Fullsend submits to Vault. Defaults tohttps://fullsend.sh/vault. It must match abound_audiencesvalue on the Vault role.
The defaults do not grant access. The Vault role must bind the expected issuer and the trusted repository and workflow identity, and its policy must limit the short-lived token to the required paths. There is no static VAULT_TOKEN or AppRole fallback.
secrets
Selects the source of each eligible runner secret. Only these names are accepted: JIRA_TOKEN, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS, and FULLSEND_GITHUB_RUNNER_SECRETS.
connection— Aconnectionsentry, ornative. If you omit it, the secret uses its forge-native source as before. Referencing an undeclared connection is a validation error.vault_secrets— Required when the connection haskind: vault, and only valid then. A non-empty ordered list of KV v2 API read paths, relative to/v1/and including the mount's/data/segment.
Fullsend reads the latest version of each path in order and takes the field named for the secret (for example JIRA_TOKEN) from data.data. A missing path, a path the Vault policy denies, or a record without a non-empty string field moves on to the next path. A Vault authentication, transport, or server error fails the run immediately. If no path supplies a value, the run fails. Fullsend never falls back to the native value for an explicit Vault selection.
Paths may use {{forge}}, {{repo.host}}, {{repo.owner}}, {{repo.name}}, {{repo.full_name}}, and {{org}}. Values come from the CI job's own identity (GITHUB_REPOSITORY and GITHUB_SERVER_URL on GitHub Actions; on GitLab CI the pinned job identity the scaffolded job script records, FULLSEND_PINNED_PROJECT_PATH and FULLSEND_PINNED_GITLAB_URL, not the overridable CI_PROJECT_PATH, CI_SERVER_HOST, or CI_PROJECT_ROOT_NAMESPACE pipeline variables), never from PR-head files or event-supplied repository names. A GitLab run without the pinned identity fails closed. {{repo.full_name}} keeps every nested GitLab group. On GitHub, {{org}} is available only when the repository owner is an organization. On GitLab it is the project's top-level namespace, available only when the project belongs to a group: Fullsend asks the GitLab Projects API with the job token, and a personal-namespace project, or a lookup that fails, leaves it unavailable. Each value is validated (no empty, ., or .. component, and no /, \, or control characters) and path-segment encoded. The expanded path must be relative and must not contain a scheme, authority, query, fragment, or empty, ., or .. component. An unknown or unavailable variable fails the run before Fullsend contacts Vault. The {{…}} syntax is not shell expansion.
connections merge by connection name and secrets merge by secret name across layers. A more-specific layer replaces the whole entry, including the vault_secrets list.
Authorization and trust boundary. Fullsend does not restrict Vault resolution by event type, workflow type, pipeline source, or ref, and the CLI does not compare the configuration against a Git revision. The trust boundary is in two places:
- Fullsend's supported workflows load
.fullsendconfig from the PR base commit for pull request and review events and from the default-branch event commit for issue and comment events, the same trust boundary used by other sensitive config. Connection definitions and secret selections come from that configuration. Callers control their own workflows and checkout choices. - The Vault JWT role's bound claims and policy authorize which workflow identities may authenticate and read which paths, just as the token mint does for its own credentials. The role must admit only trusted Fullsend workflows.
The job's OIDC token is sent to the connection's vault_address, and Vault-side bound claims cannot prevent that, so keep Vault connection settings in reviewed base or default-branch configuration and allow-list the Vault address in your deployment's egress policy.
Compatibility. The top-level connections and secrets keys need a Fullsend CLI that supports them. An older CLI that decodes the managed configuration strictly rejects a config that contains either key, so upgrade the CLI before adding them. Configs that use neither key are unaffected.
Forge support. On GitHub Actions, Fullsend requests the job's OIDC token for vault_audience, so the job needs id-token: write. On GitLab CI, the agent job must declare an ID token named FULLSEND_VAULT_ID_TOKEN whose aud is the connection's vault_audience. The scaffolded agent job (.gitlab/ci/fullsend-agent.yml) declares it with the default audience https://fullsend.sh/vault, so GitLab connections must keep the default vault_audience. A hand-edited aud differs from the shipped job, so repos status reports it as drift and repos install restores the default. Fullsend cannot change the audience of a token GitLab has already issued. Forgejo and local runs have no supported job OIDC integration, so an explicit Vault selection fails there. Secrets that omit connection or select native keep working on every forge.
Consumers. Resolved OTLP header values are handed to the same consumer as their native values: Fullsend's trace exporter. A resolved JIRA_TOKEN reaches only host-side scripts that declare it in a harness env.runner entry. Fullsend's own Jira client does not read JIRA_TOKEN; it keeps using FULLSEND_JIRA_TOKEN or the OAuth client credentials. Host-side scripts receive resolved values only through a harness env.runner declaration. A Vault-resolved FULLSEND_GITHUB_RUNNER_SECRETS bundle replaces any native bundle and follows the same host-side-only rules. Values are masked and registered for log redaction; each OTLP header entry value is registered too, and an entry whose value is too short to redact is rejected unless its key is a known routing label (tenant or x-scope-orgid). They are never written to config files or placed in the agent sandbox.
artifacts
Limits what the CI run artifact publishes: the fullsend-<agent> artifact on GitHub Actions and the job artifact on GitLab CI. For a walkthrough, see Run artifacts and private data.
artifacts:
content: all # every run: all (default) | metadata | none
by_source: # per run source; the stricter level wins
jira: metadata # runs started from a Jira issueThe runner leaves output/ untouched, so fullsend eval-measure and post-scripts read the full run. fullsend prepare-artifacts then builds a filtered copy, and CI uploads only that copy (ADR 0161).
| Level | Artifact holds |
|---|---|
all | Everything in output/. This is the default, so an unset block keeps the artifact as before. |
metadata | Only metrics.json, eval-measurements.jsonl and run-telemetry.jsonl of each run directory, with content removed as listed below. |
none | No artifact is uploaded. The job still succeeds. |
Under metadata:
metrics.jsonis copied as written. It holds counts, costs, model fallback reasons and runner paths.The telemetry copy loses every attribute and event that content capture adds (
gen_ai.input.messages,gen_ai.output.messages,fullsend.content.*and the other GenAI content attributes).The telemetry copy also loses span status messages, exception messages and stack traces, and the pre-script skip reason (
fullsend.prescript.skip_reason;fullsend.prescript.skippedstays).In the measurements copy, every row labelled
skipgets a fixed explanation, because skip explanations can quote pre-script output.If a record of the telemetry or measurements file can't be parsed, that file is left out.
Every
iteration-<N>/directory,security/findings.jsonland any other file is left out.content— The level for every run. Unset meansall.by_source— Levels for runs started from one source. Keys are the normalized event'ssource.system, the same value CEL triggers see asevent.source.system. Today's adapters emitgithub,gitlabandjira.manualandscheduleare reserved source names that no adapter emits yet; an entry for them is accepted but matches no run. A later adapter's source name works as a key with no schema change: validation rejects unknown levels, not unknown keys. Keys must be lowercase with no surrounding spaces;Jira: noneis rejected with a hint to usejira, both by config validation and byfullsend prepare-artifacts, which then prepares nothing.
Resolution. The runner picks one level per run: the stricter of content and the by_source entry for the run's source. A source with no entry gets content. none is stricter than metadata, which is stricter than all, so a by_source entry can tighten a run's level but never loosen content. With content: none and by_source: {jira: metadata}, a Jira run uploads nothing.
Run source. fullsend prepare-artifacts finds the source in this order and prints the rule it applied on stderr:
- A run with a valid normalized event uses its
source.system, trimmed and lowercased before the lookup. - A run with no normalized event in any payload, on GitHub Actions, started by a native GitHub event (
issues,issue_comment,pull_request,pull_request_target,pull_request_revieworpull_request_review_comment) isgithub. This covers the standard GitHub stage jobs, which receive no normalized event. - Everything else is unknown: manual and scheduled runs, a dispatch without a valid normalized event, a dispatch payload that names a source in
_normalized_event.source.systemwhose event is invalid or names a different source, and a GitLab event too large for the dispatch payload. There is no other forge fallback. A run with an unknown source gets the strictest ofcontentand everyby_sourceentry; when that is stricter thancontent, the rule line is a warning (and a GitHub Actions warning annotation).
Warning. A run from an external tracker (a source other than github, gitlab, forgejo, manual or schedule) that uploads at all logs a warning, and a GitHub Actions warning annotation, unless the repository set content explicitly in any layer, has a by_source entry for that source, or is known to be private.
Fails closed. If the level cannot be resolved — an invalid level, a config file that cannot be loaded, an unreadable event, or a CLI too old to know fullsend prepare-artifacts — the artifact directory is empty and no artifact is uploaded. The raw output/ is never uploaded in its place.
Layers. Across config.base.yaml and config.yaml, an explicit content overrides and by_source merges per key. When fullsend repos writes managed configuration from the repos.yaml manifest, its safety gate (ADR 0122) treats lowering an effective level toward all (for example by dropping a by_source entry or a base's content) as a relaxation, so the proposed config.yaml must declare that key explicitly. The gate does not check a direct commit to config.yaml or config.base.yaml; that change goes through the repository's normal review and CODEOWNERS.
by_source looks only at where the run started. For when to choose each level, what metadata still publishes and what follow-up workflows lose, see Run artifacts and private data.
progress
Limits what fullsend run prints to the CI job log while an agent runs, and the GitHub Actions annotations that come with it (ADR 0163). On a public repository, anyone can read the job log until log retention expires.
progress:
verbosity: full # every run: full (default) | tools | quiet
by_source: # per run source; the stricter level wins
jira: quiet # runs started from a Jira issue| Level | The log shows |
|---|---|
full | Everything, as before. This is the default, so an unset block leaves the log unchanged. |
tools | Everything except the model's reasoning and replies: tool lines, task and status progress, token counts, errors, validation output and the result. Tool lines and task labels can still carry text from the source, so use quiet for a source that isn't public. |
quiet | Only lines fullsend writes from its own fields. Text from the agent or the source is left out; see the lists below. |
At quiet:
Shown: the heartbeat, the model, event kinds and states (
Task — running,Status: hook — running; a value fullsend does not set itself prints asother), token counts, cost, error types and transcript error types (an unknown type prints asother), validation passed or failed, output file, transcript and scan finding counts, failed step names, and the result.Left out: reasoning, replies, tool lines, task labels, status details, error messages, plugin and retry messages, validation output, output file and transcript names, the error text of a failed extraction step and the agent CLI's stderr. No notice carries agent or source text: the notices that remain hold fullsend's own fields, such as
Agent completed (4m12s).Errors: transcript
::error::annotations carry the error type only. Once the run has started (from sandbox setup on), its final error prints as this fixed message, and telemetry keeps the full text:textagent run failed (error details are not printed at progress level quiet; see telemetry or the run artifact)A setup error before that, such as a config or provider error, prints in full. The level covers the job log only: the status comment on the issue or pull request still carries the full run error (#9627).
Agent CLI stderr at quiet. The agent CLI (Claude Code, pi, Codex or OpenCode) writes its own diagnostics to stderr, and they can quote what the agent read. At quiet, fullsend writes that stderr to agent-stderr.log in the iteration directory, next to output.jsonl, instead of the job log. The log gets one line with the count, never the text, even when the run fails:
Agent CLI stderr: 3 line(s) kept out of the log at quiet, in agent-stderr.logThe file follows the same artifacts rule as the transcripts: all uploads it, while metadata and none leave it out. At full and tools, stderr goes to the job log as before.
Only the printed log changes. Telemetry spans, Level 3 content capture (ADR 0050), the validation feedback that the next iteration gets, and the run artifact still receive everything. To keep reasoning and tool content under quiet, export it over OTLP to a backend you control (see Distributed tracing), and set artifacts separately for the run artifact.
verbosity— The level for every run. Unset meansfull.by_source— Levels for runs started from one source. Keys follow the same rules asartifacts.by_source: the normalized event'ssource.system, lowercase with no surrounding spaces, and open strings, so a later adapter's source name works with no schema change.
Resolution. The stricter level wins: the runner uses the stricter of verbosity and the by_source entry for the run's source, where quiet is stricter than tools, which is stricter than full. A source with no entry gets verbosity.
fullsend runfinds the run's source the same way asartifacts: a valid normalized event, else a native GitHub event.- A run whose source is unknown gets the strictest of
verbosityand everyby_sourceentry. - When the level isn't
full, the run prints one line naming the level and how it was chosen, for example:
Progress log: quiet (run source "jira" from the normalized event)Fails closed. If the level can't be resolved, for example because of an invalid level or a by_source key that isn't lowercase, the run logs at quiet. An event file that can't be read or parsed doesn't get that far: the run stops before it starts the agent, with reading event file ... or parsing event file ....
Layers. Across config.base.yaml and config.yaml, an explicit verbosity overrides and by_source merges per key. The fullsend repos safety gate (ADR 0122) treats lowering an effective level toward full as a relaxation, as it does for artifacts.
Logs written by pre-scripts and post-scripts aren't covered; those scripts are the repository owner's own code.
trace_context
The repository's trace-context keys (ADR 0154): its installation ID, the public keys that verify its trace-context envelopes, and the name of the secret that holds its private signing key. Every value in the block is public. fullsend repos install generates the keys of GitHub repositories (see Trace Context Reference — Key lifecycle). Nothing signs or verifies an envelope with them yet.
installation_id— Identifies the repository's key set: exactly 32 lowercase hex characters (128 bits), not all zero. Install keeps it through recovery, rotation and reinstall while therepos.yamlentry keeps itstrace_context; a fully uninstalled repository declared again without it starts a new installation.signing_key.secret— The secret that holds the private signing key. It must be exactlyFULLSEND_TRACE_SIGNING_KEY. The key itself never appears in configuration.verification_keys.active— The public key of the current signing key: standard base64, with padding, of a 32-byte Ed25519 public key.verification_keys.retained— Optional. Earlier public keys, in the same form, so that envelopes signed with their private keys still verify. Within an installation, install never removes one; enrolling a fully uninstalled repository again replaces the whole block.
On GitHub, fullsend repos install records the block in the repository's concrete repos.yaml entry as config.trace_context. Install renders the block into the managed .fullsend/config.yaml. Commit the repos.yaml changes install makes. Only a concrete repository entry may declare it: manifest validation rejects it in defaults.config, github.config, gitlab.config and glob entries. repos install also rejects a configuration preset or an existing .fullsend/config.base.yaml that contains it, and github setup rejects a --config preset that contains it. config.base.yaml never supplies the block.
A block must be complete: it needs installation_id, signing_key.secret and verification_keys.active. No two keys may share a key ID (the first 8 bytes of the SHA-256 hash of the public key), so a key cannot be both active and retained or be listed twice. Validation errors name the field, for example trace_context.verification_keys.retained[1], and never show its value. A value of the wrong YAML type, such as text where signing_key needs a mapping, fails parsing before validation. The parse error can quote the value's first characters, and fullsend repos set repeats the whole value when it is not the mapping or list the path needs. fullsend lint reports a malformed block in .fullsend/config.yaml, manifest validation refuses one in repos.yaml, and fullsend run fails on one before it creates the sandbox.
Installation model
This reference documents the per-repo config format (stored in .fullsend/config.yaml within the target repository). Per-repo is the only supported installation model. Per-org installation was removed (ADR 0044). Fullsend rejects a config.yaml that uses the old per-org format, which is any file with top-level dispatch, repos, or defaults keys.
Layered configuration
Per-repo config supports a two-file layered system:
| File | Role |
|---|---|
config.yaml | Overlay — repo-specific customization (writable) |
config.base.yaml | Base — vendor preset or shared baseline (read-through) |
Fields unset in the overlay fall through to the base layer, then to compiled-in code defaults. For complete merge rules, see Layered Config Reference.
See also
- Layered Config Reference — precedence, merge rules, and code defaults for every field
- Harness Field Reference — fields available in harness YAML files (per-agent configuration)
- Configuring GitHub — initial per-repo setup
- Configuring GitLab — initial per-repo setup
- Bring Your Own Agent — agent registration and harness authoring
- Configuring Agent Behavior — tuning agents via config and harness
fullsend agent— CLI commands for managing registered agents
