ADR 0008: Reusable workflows for credential isolation (undecided)

[ralphbean]

Summary

• Proposes reusable workflows so secrets (GitHub App private key) live only in .fullsend repo
• Enrolled repos invoke the reusable workflow via workflow_call, never touching secrets directly
• Status: Undecided — the premise that workflow_call provides credential isolation needs experimental validation
• Experiment plan documented: test whether calling workflows can access called workflow secrets
• Three options compared: reusable workflows, org-level secrets, external secret injection

Dependencies

• Depends on ADR 0007: GitHub Actions as initial execution platform #106 (ADR 0007: GitHub Actions as initial execution platform)

🤖 Generated with Claude Code

[ifireball]

Perhaps we can focus on leveraging workflow authorization instead of protecting long-lived secrets. The per-workflow token that GitHub issues in GITHUB_TOKEN for example, contains the REF of the reusable workflow in its job_workflow_ref field.

We can use AgentGateway to inspect the token on the road to the LLM in order to avoid having to make IT setup the trust for us in IAM or the GCP/Vertex equivalent.

[gbenhaim]

IMO the only valid solution is to use oidc federation. It's the santdard nowadays and very easy to configure. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-google-cloud-platform

[ifireball]

IMO the only valid solution is to use oidc federation. It's the santdard nowadays and very easy to configure. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-google-cloud-platform

Defining this needs a bunch of permissions on the Google Cloud side that IT does not seem to grant us:

• roles/iam.workloadIdentityPoolAdmin
• roles/iam.serviceAccountAdmin
• roles/resourcemanager.projectIamAdmin
• roles/serviceusage.serviceUsageAdmin

We wither need to start negotiating with IT to get those, or consider Agent Gateway

[ralphbean]

I think the OIDC federation vs long-lived secrets decision is orthogonal — or at least layered on top of this one.

The core thing I want to decide here is that we isolate the right to act as the agent in a "namespace" where the owners of the individual repos don't have the ability to execute arbitrary code or arbitrary workflows. Whether it's an OIDC JWT or a long-lived secret, the owners of individual repositories in the org can't access them directly. At best, they'd have to get the agent to exfiltrate them — but let's take that up in a separate decision around sandboxing the agent runtime.

I've updated the ADR to sharpen this framing: Option 3 (OIDC/external secrets) is now presented as complementary to the execution isolation decision, not as a peer alternative. It also notes that job_workflow_ref in GitHub's OIDC token could actually reinforce Option 1's isolation — so the two approaches compose well.

[gbenhaim]

Maybe I missed something, why do we need a github app? The GITHUB_TOKEN provided by default to workshops doesn't have enough permissions?

[gbenhaim]

I'm not sure about the central repo approach. It means that credentials are going to be shared by different users and it's difficult to see the benefits of it without more examples on which secrets are going to be stored.

[gbenhaim]

I think the OIDC federation vs long-lived secrets decision is orthogonal — or at least layered on top of this one.

The core thing I want to decide here is that we isolate the right to act as the agent in a

Does it mean there is a single agent in fullsend everyone should use?

"namespace" where the owners of the individual repos don't have the ability to execute arbitrary code or arbitrary workflows. Whether it's an OIDC JWT or a long-lived secret, the owners of individual repositories in the org can't access them directly. At best, they'd have to get the agent to exfiltrate them — but let's take that up in a separate decision around sandboxing the agent runtime.

I've updated the ADR to sharpen this framing: Option 3 (OIDC/external secrets) is now presented as complementary to the execution isolation decision, not as a peer alternative. It also notes that job_workflow_ref in GitHub's OIDC token could actually reinforce Option 1's isolation — so the two approaches compose well.

[waynesun09]

Question on the workflow_call shim pattern and credential isolation.

The shim workflow in enrolled repos passes the App private key to the reusable workflow:

jobs:
  agent:
    uses: {org}/.fullsend/.github/workflows/agent.yaml@main
    secrets:
      APP_PRIVATE_KEY: ${{ secrets.FULLSEND_APP_PRIVATE_KEY }}

For this to work, the enrolled repo must have access to FULLSEND_APP_PRIVATE_KEY (either as an org-level secret scoped to that repo, or copied to it). This means the private key is accessible to any workflow in the enrolled repo — a malicious PR adding a new workflow or modifying the shim could exfiltrate it.

workflow_call doesn't actually isolate credentials here — the caller must already have the secret in order to pass it. The reusable workflow runs on the calling repo's runner, not the .fullsend repo's runner, so there's no execution boundary that protects the key.

From the PR #119 experiment (nonflux/integration-service), the full workflow approach (complete agent workflows in the target repo, referencing org secrets directly) has the same credential exposure but avoids the cross-repo dependency. The tradeoff is update burden at scale vs. a single point of failure in .fullsend.

The only architecture that truly isolates the private key from enrolled repos would be a relay pattern — a lightweight service (Cloud Run, Lambda) that receives webhooks, holds the private key, mints a scoped installation token, and passes just the token to the enrolled repo's workflow via workflow_dispatch input. This breaks the "zero infrastructure" goal but is the only way the key never touches enrolled repos.

Is the credential isolation in this ADR's title referring to a different isolation boundary than key isolation from enrolled repos?

[ralphbean]

Yeah, agreed - workflow_call is unacceptable; let's explore workflow_dispatch.

[ralphbean]

Dropping this. See #167