Skip to content

docs(ci): document e2e-azure OIDC federated credential setup#192

Merged
yeongseon merged 1 commit into
mainfrom
fix/oidc-maintainer-docs-183
Jul 4, 2026
Merged

docs(ci): document e2e-azure OIDC federated credential setup#192
yeongseon merged 1 commit into
mainfrom
fix/oidc-maintainer-docs-183

Conversation

@yeongseon

Copy link
Copy Markdown
Owner

Summary

Closes part of #183 (documentation only — items 1-4 require Azure portal access).

Adds maintainer-facing documentation for the OIDC federated credential required by the e2e-azure workflow's Azure login step. The repo rename to add the -python suffix invalidated the existing federated credential, producing AADSTS700213: No matching federated identity record found on tag pushes.

Changes

docs/testing.md

  • Fixed stale trigger text in the Real Azure E2E Tests > Workflow section ("weekly schedule (Mondays 02:00 UTC)" → "Tag push (v*) or manual (workflow_dispatch)").
  • Clarified that AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID come from the azure-e2e GitHub Environment, while AZURE_LOCATION is read from the vars context with a fallback to koreacentral.
  • Added new Federated Credential (OIDC) Setup subsection documenting:
    • The exact OIDC subject: repo:yeongseon/azure-functions-validation-python:environment:azure-e2e.
    • Subject composition (repo:<owner>/<repo>:environment:<environment_name>) with explicit note that <owner>/<repo> is the GitHub repo slug — not the PyPI package name (azure-functions-validation) or the Python import name (azure_functions_validation).
    • Case-sensitivity warning and rename failure mode.
    • Reference to GitHub OIDC and Microsoft federated identity docs.
  • Added new Troubleshooting > AADSTS700213 subsection with typical causes (rename, environment change, wrong app registration) and recovery steps.

.github/workflows/e2e-azure.yml

  • Added inline maintainer comment block above environment: azure-e2e in the deploy_and_test job stating the expected OIDC subject and pointing to docs/testing.md. Placed near environment: (not near azure/login) because the environment declaration is what drives the OIDC sub claim.
  • Added a one-line cross-reference comment above environment: azure-e2e in the cleanup job.

What this PR does NOT do

This PR addresses only acceptance item #5 of #183 ("Add a short maintainer note documenting the expected OIDC subject"). Items 1–4 require Azure-side action that cannot be performed from code:

After the maintainer applies the Azure-side fix and re-runs the workflow, this issue can be closed.

Validation

  • python3 -c "import yaml; yaml.safe_load(open('.github/workflows/e2e-azure.yml'))" → OK.
  • mkdocs.yml already includes docs/testing.md under Contributing → Testing, so the new subsections are discoverable in the published docs without nav changes.

Review process

  • Oracle design review (full project context preserved across review and verification turns).
  • Oracle implementation review fixed one inaccuracy (AZURE_LOCATION source) before commit.

Adds maintainer-facing documentation for the OIDC federated credential
required by the e2e-azure workflow's Azure login step. The repo rename
to add the '-python' suffix invalidated the existing federated
credential, causing AADSTS700213 failures on tag pushes.

- docs/testing.md: new 'Federated Credential (OIDC) Setup' subsection
  documenting the exact OIDC subject
  (repo:yeongseon/azure-functions-validation-python:environment:azure-e2e),
  subject composition (owner/repo vs PyPI/import name), case-sensitivity,
  and a new 'Troubleshooting' subsection for AADSTS700213 with typical
  causes and recovery steps. Also corrects stale trigger text and
  clarifies the source of secrets vs vars.
- .github/workflows/e2e-azure.yml: adds inline maintainer comments
  above the 'environment: azure-e2e' declaration in both jobs pointing
  to the docs and stating the expected OIDC subject.

This PR satisfies acceptance item #5 only. Items 1-4 require Azure
portal access to (1) confirm the AD app registration behind
AZURE_CLIENT_ID and (2) add or update the federated credential to match
the new subject, then re-run the workflow to verify.

Refs #183
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant