feat: built-in deployment lookup so consumers don't reimplement it per workflow

[caffeinum]

Background

url-map requires a concrete preview URL. For platforms that post to GitHub's Deployments API (Vercel, Mintlify, Fly, etc.) that URL lives in deployment_status.target_url — readily available when the workflow is triggered by on: deployment_status.

But for on-demand triggers (pull_request: types: [labeled], issue_comment), there's no deployment payload — only a PR ref. Consumers currently work around this with a pre-step that lists deployments for the PR's head sha and feeds the result into url-map. Example from team2027/docs#17:

- id: resolve
  uses: actions/github-script@v9
  with:
    script: |
      // ~50 lines: fetch PR if issue_comment, list deployments, find latest success...
- uses: team2027/evals-action@v0.7.0
  with:
    url-map: '{"acme.com": "${{ steps.resolve.outputs.deployment-url }}"}'

This is the same dance every consumer with on-demand triggers will write. Worth pulling into the action.

Proposal

Add an input that lets the action resolve the deployment itself when url-map references a placeholder:

- uses: team2027/evals-action@v1
  with:
    prompt-id: ...
    # Action looks up the latest successful deployment for the PR head sha
    # and substitutes the URL itself. Skips with a warning (not failure)
    # if nothing's deployed yet.
    url-map: '{"acme.com": "auto:deployment"}'

Or a dedicated input that's less stringly:

with:
  resolve-deployment: true
  url-map: '{"acme.com": ""}'   # empty values get resolved
  # or
  deployment-environment: production   # optional filter

Behavior

• Identify the head sha from event context (already handled — pull_request.head.sha, issue_comment → pulls.get, deployment_status.deployment.sha).
• GET /repos/{owner}/{repo}/deployments?sha=<sha> then walk statuses for the first success (optionally filtered by deployment-environment).
• If nothing found, log a warning and exit without starting an eval (matches today's fork-PR bail).
• Permission required: deployments: read. Document it.

Why now

team2027/docs#17 adds this lookup inline. Filing this so the next 2-3 consumers don't re-derive it from scratch — at that point pull it upstream.

Open questions

• Marker syntax: auto:deployment placeholder vs. dedicated boolean input. Latter is cleaner; former is one input fewer in the schema.
• Multi-deployment matching: which environment wins when a sha has both Preview and Production? Probably take the most recent, or require the input.
• Do we ever want this for template-vars too (e.g. CLI install URLs)? Probably not — those are stamped per commit by upstream tooling, not deployments.

[caffeinum]

@codex brainstorm implement this

[chatgpt-codex-connector]

To use Codex here, create an environment for this repo.