Skip to content

Translations call Claude on Amazon Bedrock with one-hour OIDC credentials, and skip while no AWS role is set - #728

Open
zlareb1 wants to merge 8 commits into
mainfrom
i18n-keyless-bedrock
Open

zlareb1 wants to merge 8 commits into
mainfrom
i18n-keyless-bedrock

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Changelog category (leave one):

  • CI Fix or Improvement (changelog entry is not required)

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

...

Why

The translations workflow needed the repository secret ANTHROPIC_API_KEY. The secret was never added, so every run on main failed with "ANTHROPIC_API_KEY is not set" and no page was translated. A stored API key is also a long-lived credential in a job that can push branches. Translations now authenticate with no stored secret: the job trades its GitHub OIDC token for one-hour AWS credentials and calls Claude on Amazon Bedrock.

  • scripts/i18n/translate.py sends the same Messages API request to Bedrock's bedrock-mantle endpoint (https://bedrock-mantle.<region>.api.aws/anthropic/v1/messages, model anthropic.claude-sonnet-5-5). Each request is signed with AWS Signature Version 4 using only the standard library. The script refuses credentials that have no session token, so a long-lived access key cannot be used. The ANTHROPIC_API_KEY path is removed. The USD cap, the verifier and the retry rules are unchanged. The stamp still records claude-sonnet-5-5, so no page goes stale because of this change.
  • .github/workflows/i18n.yml runs its job in the environment i18n, gets id-token: write and runs aws-actions/configure-aws-credentials (pinned by sha, v6.3.0) with role-to-assume: vars.LOOM_I18N_AWS_ROLE_ARN and aws-region: vars.LOOM_I18N_AWS_REGION. These are repository variables because an ARN is not a credential. The credentials are passed as step outputs into the Translate step only (output-env-credentials: false); the steps that push the branch never see them.
  • While LOOM_I18N_AWS_ROLE_ARN is empty, the job is skipped by its if:, so pushes to main no longer leave a red run. The skip is on the job rather than a step so that the job does not enter the environment i18n. A job that enters it records a deployment, and that would create the environment without its deployment-branch rule.
  • CONTRIBUTING.md#translations gives the IAM role's trust policy (OIDC provider token.actions.githubusercontent.com, audience sts.amazonaws.com, sub repo:ClickHouse/loom:environment:i18n) and its permission policy. Trusting the environment instead of ref:refs/heads/main keeps every other job on main that has id-token: write from assuming the role. The environment's deployment branches limit it to main, which covers both a push and a manual run there. It also shows how a contributor runs the script with temporary credentials.

Design choices:

  • bedrock-mantle instead of bedrock-runtime InvokeModel. The Messages API on bedrock-mantle takes the request body the script already builds, output_config.effort included. Its IAM action is bedrock-mantle:CreateInference. That action authorizes the account's project rather than a model ARN, so the permission policy limits it to one model with the bedrock-mantle:Model condition.
  • API version 2026-10-21. The Claude-on-Bedrock page sends anthropic-version: 2026-10-21 to bedrock-mantle in its example (https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and the versioning notes say Bedrock accepts it for Claude 4.7 and later. The request uses none of the fields that version removes (temperature, top_p, top_k). The direct Messages API callers elsewhere in the repository keep 2023-06-01.
  • Standard-library SigV4 instead of the anthropic[bedrock] SDK. The script and its unit tests have no third-party dependencies. The SDK client would pull a dependency tree into a job that has contents: write and AWS credentials, and each package in it would need a hash pin. The signer is about 40 lines. A unit test pins its output to botocore's SigV4Auth for the same request.

Scope and risk

This touches the translations workflow, its script and tests, and the contributor docs. The server, the SDKs and the dashboard are unchanged. Until the role and variables exist, the workflow does nothing. The first real request will settle two facts that unit tests cannot check: whether Bedrock serves Claude Sonnet 5.5 in the chosen region, and whether the model value matched by the bedrock-mantle:Model condition is anthropic.claude-sonnet-5-5. A wrong value fails the run with a 403 and spends nothing. The cost cap still uses Anthropic's list prices, and Bedrock bills at its own, so the cap is approximate.

Compatibility, rollout and rollback

  • Wire: none.
  • Operator steps: create the environment i18n with deployment branches set to main only (Settings → Environments). Create an IAM role in an AWS account where Bedrock has Claude Sonnet 5.5 enabled, with the trust and permission policies in CONTRIBUTING.md#translations. Then set the repository variables LOOM_I18N_AWS_ROLE_ARN and LOOM_I18N_AWS_REGION. The ANTHROPIC_API_KEY secret is no longer read.
  • Breaking: running python -m scripts.i18n.translate update locally now needs temporary AWS credentials instead of an Anthropic API key.
  • Rollback: a revert restores the API-key path. Nothing is stored.

Tests

  • tests/unit/test_i18n.py: each AWS variable is read into its own field; the request names anthropic.claude-sonnet-5-5. The SigV4 authorization header equals botocore's SigV4Auth output for the same request, credentials and time. A call posts the signed request to the bedrock-mantle URL, and a retry after a 503 is signed again with its own date. update refuses to start when any of AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN or AWS_REGION is missing. The existing update tests run with AWS credentials in the environment.
  • ruff format --check, ruff check, make mypy-gate (0 new errors), and .venv/bin/python -m pytest tests/unit/test_i18n.py tests/unit/test_doc_links.py tests/unit/test_public_copy.py tests/unit/test_agent_instructions.py: all passed. The full tests/unit suite passes except test_document_extraction.py::test_deeply_nested_hidden_html_parses_in_bounded_time, a wall-clock bound that fails on a loaded shared host and passes in CI. The workflow parses as YAML. The merge push touches neither README.md nor docs/, so it starts no run. A manual run on main after the merge, with the variable still empty, checks the skip path.
  • No paid run. The first real run happens once the variables are set.

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated (an agent wrote most of the diff): Claude Code. It checked the endpoint, model id and IAM action against the Claude-on-Bedrock and AWS service authorization pages, and checked the signer against botocore.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass; the integration suite passes if server behaviour changed. (Server behaviour is unchanged; the one local unit failure is the wall-clock test named under Tests.)
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.

🤖 Generated with Claude Code

zlareb1 and others added 8 commits November 16, 2026 07:19
…ials

The translations workflow no longer reads ANTHROPIC_API_KEY. It exchanges
its GitHub OIDC token for one-hour AWS credentials of the role in
vars.LOOM_I18N_AWS_ROLE_ARN and hands them to the Translate step only.
translate.py signs each Messages API request to bedrock-mantle with SigV4
and refuses credentials without a session token. While no role is set the
job writes a step-summary line and succeeds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…is signed again

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…t; model-policy note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…hide secrets in repr

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…r test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…es go on the repository

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>

This branch has not been deployed

No deployments
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