Document Foundry auto-deploy + optional OAuth registry login

[anand-testcompare]

What changed

• Add docs/foundry-auto-deploy.md describing the OpenAPI -> Foundry functions import path and linking from existing Foundry docs.
• Surface Foundry UI screenshots (artifact repo tags, OpenAPI schema view, function call/query panel), including one in README.md.
• Update /.github/workflows/publish-foundry.yml to optionally mint a short-lived OAuth2 token (client credentials) for registry login, with a fallback to FOUNDRY_TOKEN.

Why

Make the Foundry deployment story easier to understand and easier to automate: the OpenAPI contract becomes the single source of truth for function registration, and auth options are clearer for CI.

Notes

• The OAuth path is best-effort and gated by enrollment support; existing FOUNDRY_TOKEN flow continues to work unchanged.

Summary by CodeRabbit

• New Features

  • Added OAuth2-based authentication option for Foundry registry with token masking; maintains fallback to static token configuration.
  • Introduced Foundry Auto-Deploy workflow for converting OpenAPI contracts into importable Foundry functions.

• Documentation

  • Enhanced deployment guides with new Foundry Auto-Deploy runbook and OpenAPI compute module instructions.

[railway-app]

🚅 Deployed to the dspy-reference-examples-pr-21 environment in dspy-reference-example

Service	Status	Web	Updated (UTC)
dspy-reference-examples	✅ Success (View Logs)	Web	Feb 15, 2026 at 5:27 pm

[coderabbitai]

Walkthrough

This PR introduces OAuth2-based authentication for Foundry registry workflows with fallback to legacy static tokens, alongside comprehensive documentation for the Foundry auto-deploy workflow that converts OpenAPI contracts into importable Foundry functions.

Changes

Cohort / File(s)	Summary
OAuth2 Workflow Integration .github/workflows/publish-foundry.yml	Adds OAuth2-based login flow for Foundry registry with FOUNDRY_OAUTH_CLIENT_ID and FOUNDRY_OAUTH_CLIENT_SECRET support. Implements runtime token acquisition with fallback to FOUNDRY_TOKEN, includes token masking in logs for security, and JSON parsing for access_token extraction.
Documentation Updates README.md, docs/foundry-auto-deploy.md, docs/deploy-ci.md, docs/foundry-openapi-runbook.md	New comprehensive documentation for Foundry auto-deploy workflow explaining OpenAPI-to-functions conversion process, container image approach, generation/validation steps, and authentication guidance. Adds cross-references between deployment docs and environment variable clarifications.

Sequence Diagram(s)

sequenceDiagram
    participant GH as GitHub Actions
    participant OAuth as OAuth Provider
    participant Foundry as Foundry Registry
    
    GH->>GH: Check for OAuth credentials<br/>(CLIENT_ID, CLIENT_SECRET)
    alt OAuth Credentials Present
        GH->>OAuth: Request access token<br/>(client_id, client_secret)
        OAuth-->>GH: Return access_token (JSON)
        GH->>GH: Parse & extract token<br/>from response
        GH->>GH: Mask token in logs
        GH->>Foundry: Login with OAuth token
    else OAuth Credentials Absent
        GH->>Foundry: Login with FOUNDRY_TOKEN<br/>(legacy path)
    end
    Foundry-->>GH: Authentication successful
    GH->>Foundry: Publish artifacts

Loading

Possibly related PRs

• Add Foundry publish workflow + versioned tags #16: Directly introduced OAuth2 login and token handling logic now expanded in this PR.
• Add versioned Foundry artifact tags (auto-increment) #14: Previously modified Foundry registry publish workflow conditions that this PR enhances with OAuth2 support.

Poem

🐰 A hop through tokens, OAuth's way,
No static secrets need to stay,
With masks and scopes, we dance with grace,
Runtime tokens take their place!
Foundry calls—our docs now show the path, ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately captures the main changes: documentation updates for Foundry auto-deploy workflow and optional OAuth-based registry login in the CI workflow.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch foundry-auto-deploy-docs

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/foundry-auto-deploy.md`:
- Around line 68-70: Update the "Auth Notes" section to be consistent with
docs/deploy-ci.md by changing the guidance about FOUNDRY_TOKEN to indicate it is
a short-lived token that requires refreshing per publish window (instead of
recommending a long‑lived token), and add a preferred OAuth2 client credentials
option describing the required vars FOUNDRY_URL, FOUNDRY_OAUTH_CLIENT_ID, and
FOUNDRY_OAUTH_CLIENT_SECRET as the recommended CI auth method; keep the legacy
FOUNDRY_TOKEN paragraph as an alternative and advise creating a dedicated
non‑admin Foundry user with Edit permission if using it.

🧹 Nitpick comments (1)

.github/workflows/publish-foundry.yml (1)

136-147: Consider adding error handling for OAuth token response parsing.

If the OAuth token endpoint returns a non-200 response or an unexpected JSON structure (e.g., missing access_token), line 145 will fail with an unhelpful KeyError. Adding defensive parsing would improve debuggability.

♻️ Suggested improvement for error handling

             token_json="$(
-              curl -fsS -X POST "${foundry_url}/multipass/api/oauth2/token" \
+              curl -fsS --max-time 30 -X POST "${foundry_url}/multipass/api/oauth2/token" \
                 -H "Content-Type: application/x-www-form-urlencoded" \
                 --data-urlencode "grant_type=client_credentials" \
                 --data-urlencode "client_id=${FOUNDRY_OAUTH_CLIENT_ID}" \
                 --data-urlencode "client_secret=${FOUNDRY_OAUTH_CLIENT_SECRET}" \
                 "${scope_arg[@]}"
             )"

-            oauth_token="$(python -c 'import json,sys; print(json.loads(sys.stdin.read())["access_token"])' <<<"${token_json}")"
+            oauth_token="$(python -c '
+import json, sys
+data = json.loads(sys.stdin.read())
+if "access_token" not in data:
+    print("Error: OAuth response missing access_token. Response:", data.get("error", data), file=sys.stderr)
+    sys.exit(1)
+print(data["access_token"])
+' <<<"${token_json}")"

This adds a 30-second timeout to prevent indefinite hangs and provides a clearer error message if the OAuth response is malformed or contains an error.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Auth notes are inconsistent with other docs and missing OAuth2 option.

Two issues:

1. Inconsistency: This doc recommends a "long-lived token" for FOUNDRY_TOKEN, but docs/deploy-ci.md (line 62) states FOUNDRY_TOKEN is "short-lived" and needs refreshing before each publish window.

2. Missing OAuth2 guidance: The workflow now supports OAuth2 client credentials as the preferred authentication method (via FOUNDRY_URL, FOUNDRY_OAUTH_CLIENT_ID, FOUNDRY_OAUTH_CLIENT_SECRET), but this section only mentions the legacy FOUNDRY_TOKEN approach.

📝 Suggested update to align auth guidance

 ## Auth Notes

-For CI, prefer a dedicated non-admin Foundry user that has **Edit** permission on the target Artifact Repository. Generate a long-lived token as that user and store it as the GitHub secret `FOUNDRY_TOKEN`.
+For CI authentication, two options are available:
+
+1. **OAuth2 (preferred)**: Configure `FOUNDRY_URL`, `FOUNDRY_OAUTH_CLIENT_ID`, and `FOUNDRY_OAUTH_CLIENT_SECRET` secrets. The workflow mints a short-lived access token at runtime.
+
+2. **Legacy token**: Generate a token from a dedicated non-admin Foundry user with **Edit** permission on the target Artifact Repository. Store it as `FOUNDRY_TOKEN`. Note: This token is short-lived and must be refreshed before each publish window.

🤖 Prompt for AI Agents

In `@docs/foundry-auto-deploy.md` around lines 68 - 70, Update the "Auth Notes"
section to be consistent with docs/deploy-ci.md by changing the guidance about
FOUNDRY_TOKEN to indicate it is a short-lived token that requires refreshing per
publish window (instead of recommending a long‑lived token), and add a preferred
OAuth2 client credentials option describing the required vars FOUNDRY_URL,
FOUNDRY_OAUTH_CLIENT_ID, and FOUNDRY_OAUTH_CLIENT_SECRET as the recommended CI
auth method; keep the legacy FOUNDRY_TOKEN paragraph as an alternative and
advise creating a dedicated non‑admin Foundry user with Edit permission if using
it.