Skip to content

A-2027: Document GCP KMS managed keys for signed pipelines - #3171

Open
zhming0 wants to merge 2 commits into
mainfrom
a-2027-document-gcp-kms-signing
Open

zhming0 wants to merge 2 commits into
mainfrom
a-2027-document-gcp-kms-signing

Conversation

@zhming0

@zhming0 zhming0 commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Why

The agent has supported GCP KMS for signed pipelines since v3.121.0 (buildkite/agent#3660), but the Signed pipelines page only documents self-managed JWKS keys and AWS KMS. A customer recently proposed GCP Secret Manager support in buildkite/agent#4378 because they didn't know GCP KMS was already an option.

What

Adds a "GCP KMS managed key setup" section following the structure of the AWS KMS section, based on the agent source (internal/cryptosigner/gcp/kms.go, clicommand/agent_start.go, clicommand/tool_sign.go, clicommand/pipeline_upload.go):

  • Creating an asymmetric signing key with gcloud, and the key version resource name format the signing-gcp-kms-key setting requires (projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*).
  • The GCP KMS algorithms the agent accepts and the JWS algorithm each maps to (EC P-256/P-384, RSA PSS, RSA PKCS1).
  • Agent configuration, including the BUILDKITE_AGENT_SIGNING_GCP_KMS_KEY (agent start) and BUILDKITE_AGENT_GCP_KMS_KEY (tool sign, pipeline upload) environment variables, and Application Default Credentials for authentication.
  • IAM permissions: signing agents need useToSign and viewPublicKey (roles/cloudkms.signerVerifier); verifying agents need only viewPublicKey (roles/cloudkms.publicKeyViewer) because the agent fetches the public key and verifies locally.
  • Key rotation caveat: the agent pins a single key version, so all agents must be updated together.

Also removes a stale <path to signing jwks> bullet from the AWS KMS "Sign all steps" section (the command above it has no such flag), and mentions KMS in the page's LLM description.

The agent CLI help partials and agent_attributes.yaml already include --signing-gcp-kms-key because they are generated from the agent, so no changes there.

Linear: A-2027

The agent has supported --signing-gcp-kms-key on agent start,
pipeline upload, and tool sign since v3.121.0 (buildkite/agent#3660),
but the signed pipelines page only covered AWS KMS. Add a GCP KMS
section mirroring the AWS KMS structure: key creation, agent
configuration, signing static steps, IAM permissions, and rotation.

Also remove a stale <path to signing jwks> bullet from the AWS KMS
"Sign all steps" section that doesn't match the command above it.

A-2027

Amp-Thread-ID: https://ampcode.com/threads/T-01a10f73-0a6f-727d-a4f5-1e90dc3404c7
Co-authored-by: Amp <amp@ampcode.com>
@zhming0
zhming0 requested a review from a team as a code owner October 6, 2026 04:37
@github-actions github-actions Bot added the agent label Oct 6, 2026
@buildkite-systems

Copy link
Copy Markdown

@buildsworth-bk-app buildsworth-bk-app Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The algorithm table needs a version caveat to avoid rejecting validly signed jobs on older supported agents. I also flagged a configuration value that fails when copied literally.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 36868, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

About buildsworth

Model: gpt-6.1-sol with xhigh thinking.

How to request a review: Comment @buildsworth-bk review on the PR, or request buildsworth-bk as a reviewer.

Risk labels (how buildsworth classifies risk) — buildsworth classifies risk itself from the diff. Unless repository policy already allows L2 approval, grant it by mentioning @buildsworth-bk (see approval ceiling and L2 approval grant):

  • L1 — Low risk (dep bumps, docs/copy, lockfiles, small presentational fixes). buildsworth may approve by default.
  • L2 — Standard risk (new UI, additive API fields, refactors). Approved only when repository policy or a verified grant allows it; otherwise comment-only.
  • L3 — High risk (auth, migrations, payments, secrets, perf-critical pipeline paths). Human approval required unless repository policy explicitly allows L3 approval; per-PR grants cannot allow it.

Comment thread pages/agent/self_hosted/security/signed_pipelines.md
Comment thread pages/agent/self_hosted/security/signed_pipelines.md Outdated
…fication-failure-behavior placeholder

Agent versions before 3.136.0 (go-pipeline < 0.18.0) verify KMS
signatures as ES256 regardless of the key's algorithm, so only
EC_SIGN_P256_SHA256 keys work there. Also replace the literal <warn>
placeholder, which the config parser keeps as-is and the job runner
rejects, with warn in all three sections.

Amp-Thread-ID: https://ampcode.com/threads/T-01a10f73-0a6f-727d-a4f5-1e90dc3404c7
Co-authored-by: Amp <amp@ampcode.com>
@zhming0
zhming0 requested a review from buildsworth-bk October 6, 2026 04:45

@buildsworth-bk-app buildsworth-bk-app Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both previous findings are fixed, and I found no new issues.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 36877, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

@buildsworth-bk-app
buildsworth-bk-app Bot dismissed their stale review October 6, 2026 04:46

Superseded by a newer Buildsworth review.

@buildsworth-bk-app
buildsworth-bk-app Bot removed the request for review from buildsworth-bk October 6, 2026 04:46

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants