How should users pass custom secrets to BYOA agents invoked via reusable dispatch?

[ralphbean]

Question

How is a user supposed to get a custom secret to a BYOA agent invoked through reusable dispatch with CEL expression triggering? The workflow doesn't know to explicitly "mount" their secret to an env var.

Current State

Looking at the workflow chain:

1. reusable-dispatch.yml defines a fixed set of secrets:

   • FULLSEND_GCP_WIF_PROVIDER
   • FULLSEND_GCP_PROJECT_ID
   • OTEL_EXPORTER_OTLP_TRACES_HEADERS
   • OTEL_EXPORTER_OTLP_HEADERS

2. reusable-harness-run.yml declares the same secrets and passes them to the agent run step

3. The agent execution environment has a hardcoded env: block

Per workflow-contracts.md, GHA reusable workflows don't inherit secrets - they must be explicitly forwarded at every hop. There's no escape hatch here.

Current Workarounds

Option 1: Custom poller workflow
Skip reusable-dispatch entirely and write a custom workflow that directly calls reusable-harness-run.yml. But reusable-harness-run.yml only accepts the predefined secrets, so this doesn't work either.

Option 2: Fork the workflow
Fork reusable-harness-run.yml into your repo and add your secret. Not scalable, breaks upgrades.

Option 3: Use secrets: inherit (untested)
The repo uses secrets: inherit in e2e-ok-to-test.yml, though workflow-contracts.md discourages it as a blanket pattern. If reusable-harness-run.yml used secrets: inherit, users could pass any secret. But this would break the explicit contract model the codebase currently enforces.

Potential Solutions

A. Add secrets: inherit to reusable-harness-run.yml
Would need to flow through reusable-dispatch.yml too. Goes against the explicit-forwarding principle in the docs.

B. Support a passthrough secret map
Add an input like:

inputs:
  custom_env:
    type: string  # JSON map

Callers pass '{"MY_KEY": "value"}', the workflow deserializes and injects into the agent env. Secrets would need to be stringified client-side (awkward).

C. Document the api_servers pattern
The harness api_servers: feature already lets users run a host-side proxy with custom env. The proxy script can access repository secrets, and the sandbox talks to it over localhost. This is the current "blessed" path for custom credentials, but it's not obvious from the BYOA guide.

D. Reserve a custom secret namespace
Define CUSTOM_AGENT_ENV_* secrets that the workflow auto-injects. Users set CUSTOM_AGENT_ENV_MY_KEY=... as a repo secret, workflow strips the prefix and passes MY_KEY to the agent.

Notes

Option C (api_servers) is the only one that currently works without workflow changes, but it's not well-documented for this use case.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 2:16 AM UTC · Completed 2:20 AM UTC

Commit: a66da3a · View workflow run →

[fullsend-ai-triage]

Good analysis — this covers the design space well.

Based on the repository context, Option C (api_servers) is the current blessed path and the only one that works today without workflow changes. The BYOA guide already documents api_servers with a custom env example:

api_servers:
  - name: my-api
    script: scripts/api-server.sh
    port: 8080
    env:
      API_KEY: "${API_KEY}"

The server script runs on the host side (outside the sandbox), so it has access to repository secrets via the workflow environment. The sandboxed agent then reaches it over localhost — secrets never enter the sandbox directly.

However, the BYOA guide doesn't explicitly frame this as the solution for "I need my agent to use a custom credential." That's the documentation gap. The guide shows the api_servers YAML structure but doesn't walk through the credential-proxy use case end-to-end.

A few notes on the other options:

• Option A (secrets: inherit) conflicts with the explicit-forwarding principle documented in workflow-contracts.md and would weaken the contract model.
• Option B (passthrough JSON map) has the awkward stringification problem and doesn't compose well with GHA's secret masking.
• Option D (namespace convention) is clean but requires workflow changes in both reusable-dispatch.yml and the extracted reusable-harness-run.yml (PR feat(workflows): extract harness-run into reusable workflow #6356).

Note that #879 and #881 track the full api_servers lifecycle implementation — #881 is currently labeled blocked, so there may be limitations in the current api_servers support worth checking before documenting it as the primary credential path.

Would you like to convert this into one or more concrete work items? For example:

1. A documentation issue to add a "Custom credentials" section to the BYOA guide showing the api_servers credential-proxy pattern end-to-end
2. A feature request if one of the other options (B or D) should also be pursued for cases where api_servers is too heavyweight

Or if the intent is to land Option D alongside PR #6356, that could be scoped as a follow-up PR to that extraction work.

---

Labels: This issue concerns the reusable dispatch workflow chain and BYOA agent configuration — it spans the dispatch and harness components, with a documentation gap as the primary actionable finding.