cherrypicking-pr-to-v3

# Cherry-picking a PR to v3 Since August 2026, `main` is the v4 codebase. Stable v3 releases come from the `v3` branch. A change that needs to reach customers in v3 must first merge to `main`, then be backported as a second PR against `v3` with the same changes translated back to v3 conventions. ## Should this be backported at all? v4 is the primary agent release and v3 is maintenance-only while it's supported. Before doing any work, check the change against the [Agent v3 Backport Policy](https://app.notion.com/p/buildkite/Agent-v3-Backport-Policy-3d0b8dbc2c8980368255d4c30e058d99): - **Security fixes**: always eligible for backporting to the latest v3 minor release line, but not automatically required. Check that the vulnerability actually affects v3 agents and is worth fixing there (for example, a dependency bump for a CVE in code v3 never calls may not be). - **Bug fixes**: case-by-case only. They must fix a production-affecting bug (not confusing logs or cosmetic issues) that has no backend mitigation or other workaround. In practice, we should also only backport a bug fix when it affects a major customer who can't or won't upgrade to v4. - **New features**: don't backport. Exceptions need a very, very good reason and approval from both the Agents team and product. A new feature on v3 would also mean a new v3 minor release line, which extends v3's support window by another year. The default answer for a customer issue on v3 is to fix it in v4 and ask them to upgrade, not to backport. If the change isn't clearly a security fix that matters for v3 or an eligible bug fix, stop before cherry-picking and tell the user which part of the policy it falls under. Only continue if they confirm the justification (and, for features, that Agents team and product approval has been given). Include that justification in the backport PR description. ## Workflow 1. Identify the merged PR/commit on `main` to backport. Never cherry-pick the v4 merge commit (`8aea45a`, PR #3807) itself — it is the entire v4 delta. 2. Confirm the change is eligible under the backport policy (see above). 3. Apply the change onto `v3`: with jj, `jj duplicate <rev> -d v3` (then `jj edit` the duplicate to resolve conflicts); with git, branch off `v3` and `git cherry-pick -x --no-commit <sha>`. Resolve conflicts by translating the code as described below. PRs in this repo merge as two-parent merge commits, and the change lives in the constituent commit(s), not the merge commit: `jj duplicate` of the merge commit produces an empty commit, and `git cherry-pick` refuses it without `-m 1`. Select the PR's constituent commit(s) instead. 4. Translate all v4-isms back to v3 (see checklist). 5. Raise the backport PR against `v3`. Keep the description concise: state that it is a backport of the original PR (with a link), why it qualifies under the backport policy, and any translation deviations. Do not duplicate the original PR's full description — reviewers can follow the link. 6. Do not touch the `VERSION` file unless a release is explicitly requested. ## Translation checklist (v4 → v3) ### 1. Import paths The module changed major version. Rewrite every import: ```diff -"github.com/buildkite/agent/v4/api" +"github.com/buildkite/agent/v3/api" ``` Also check string-valued package paths, not just imports: tracer names (`otel.Tracer("github.com/buildkite/agent/...")`), linker flags, generated protobuf `go_package_prefix`, doc links. Never change the v3 branch's `go.mod` module declaration. ### 2. urfave/cli: v3 → v1 `main` uses `github.com/urfave/cli/v3`; the `v3` branch uses `github.com/urfave/cli` (v1). Flags and commands are pointers in cli v3 but values in cli v1, and env vars are declared differently: ```go // main (cli v3) &cli.StringFlag{ Name: "note", Usage: "A descriptive note to record why the agent is paused", Sources: cli.EnvVars("BUILDKITE_AGENT_PAUSE_NOTE"), } // v3 branch (cli v1) cli.StringFlag{ Name: "note", Usage: "A descriptive note to record why the agent is paused", EnvVar: "BUILDKITE_AGENT_PAUSE_NOTE", } ``` | main (cli v3) | v3 branch (cli v1) | |---|---| | `import "github.com/urfave/cli/v3"` | `import "github.com/urfave/cli"` | | `&cli.Command{...}` | `cli.Command{...}` | | `[]*cli.Command` | `[]cli.Command` | | `&cli.StringFlag{...}` (and Bool/Int/etc.) | `cli.StringFlag{...}` | | `Sources: cli.EnvVars("X")` | `EnvVar: "X"` | | `Commands: []*cli.Command{...}` (subcommands) | `Subcommands: []cli.Command{...}` | | `StringSliceFlag{Value: []string{}}` | `StringSliceFlag{Value: &cli.StringSlice{}}` | | `cli.Exit(...)` | `cli.NewExitError(...)` | | `flag.Names()` | `flag.GetName()` | ### 3. Action signatures and context cli v3 actions receive a `context.Context`; cli v1 actions do not: ```go // main (cli v3) Action: func(ctx context.Context, c *cli.Command) error { ctx, cfg, l, _, done := setupLoggerAndConfig[Config](ctx, c) ... } // v3 branch (cli v1) Action: func(c *cli.Context) error { ctx := context.Background() ctx, cfg, l, _, done := setupLoggerAndConfig[Config](ctx, c) ... } ``` Named action functions translate the same way: `func fooAction(ctx context.Context, c *cli.Command) error` becomes `func fooAction(c *cli.Context) error` with `ctx := context.Background()` inside. Do not change v3's shared setup helpers to accept `*cli.Command`. ### 4. CLI accessors | main (cli v3) | v3 branch (cli v1) | |---|---| | `c *cli.Command` | `c *cli.Context` | | `c.Root().Writer` / `c.Root().ErrWriter` | `c.App.Writer` / `c.App.ErrWriter` | | `c.Args().Len()` | `len(c.Args())` | | `c.Args().Slice()` | `c.Args()` | | `c.Args().Get(0)` | `c.Args()[0]` | | `clicommand.SomeFlag.Value` (slice flag, `[]string`) | `*clicommand.SomeFlag.Value` (deref `*cli.StringSlice`) | ### 5. Tests cli v3 tests build a root `*cli.Command`, clone commands (Run mutates them), and call `app.Run(t.Context(), args)`. v3 tests use the v1 harness: ```go app := cli.NewApp() app.Commands = []cli.Command{SomeCommand} err := app.Run(args) ``` Do not copy the cli v3 command-cloning workaround into v3 tests. ## Behavioral differences — don't backport v4 breaks by accident A conflict may signal a deliberate v4 behavior change, not just code drift. Preserve v3 behavior unless changing it is the explicit purpose of the backport: - **Tracing/metrics**: v3 still has Datadog/OpenTracing and DogStatsD (`TracingBackend`, `TracingServiceName`); v4 is OpenTelemetry-only (`OpenTelemetryTracing`, `TelemetryServiceName`). Map config fields back. - **Cancellation flags**: v3 has `--cancel-grace-period` and `--signal-grace-period-seconds`; v4 replaced them with `--cancel-signal-timeout` and `--cancel-cleanup-timeout`. - **Experiments**: v4 promoted or removed several experiments (normalized artifact upload paths, resolve-commit-after-checkout, etc.). A v4 diff may lack an experiment guard because the behavior is unconditional there; the v3 backport may need to keep or add the guard. - **Hook ordering**: v4 reverses post-hook order by default; v3 does not. - **Commit verification**: v4 defaults to `strict` and only supports `strict`/`off`; v3 supports the older empty/`warn`/`strict` values. - **SSH host keys**: v4 uses `GIT_SSH_COMMAND` with `StrictHostKeyChecking=accept-new`; v3 still uses `ssh-keyscan` and `known_hosts`. - **Removed in v4, still in v3**: deprecated Docker integration, deprecated artifact flags (`follow-symlinks`), plugin env aliases, header-times streamer/API. If the v4 patch assumes these are gone, the v3 backport needs a v3-specific integration point. - **Output**: v4 intentionally changed some output (e.g. `meta-data get` gained a trailing newline). Don't pull such compatibility breaks into v3. ## Reference - Changelog: https://buildkite.com/resources/changelog/382-buildkite-agent-v4-becomes-the-stable-release-on-1-september-2026/ - Notion: "Making agent changes in the run-up to v4" (buildkite Notion, page `3b3b8dbc2c8980b5a623e6e678da893b`) - The v4 merge to main: https://github.com/buildkite/agent/pull/3807