add context input to replace workdir and source inputs

[crazy-max]

• fixes Workdir does not work or is not documented properly #294
• fixes Bad context on version 6.x.x #301
• fixes Uncertain behavior of local source #352

This PR introduces a new context input that replaces both workdir and source inputs. It resolves long-standing confusion around how bake-action determines what directory or Git reference to use when running bake.

The workdir input was originally added in #76 to support running Bake from a subdirectory inside the GitHub workspace.

Later, Git context support was added in #181 introducing a new source input. This created overlap and ambiguity between:

• workdir (local path inside workspace)
• source (Git context but can be skipped with .)

This duality has consistently caused confusion for users, as highlighted in multiple issues and discussions. Users also pointed out that naming was inconsistent with build-push-action, where the input is called context.

This unified context input aligns with build-push-action. If a local dir is detected it will use it as working directory to run Bake otherwise it will use the Git context like it does for build-push-action.

cc @ModerNews @polarathene @Clashsoft

[polarathene]

Feedback is a tad verbose, sorry about that 😓 (I repeat some things a bit, short on time to revise)

---

Rough overview

I think this change is alright (with some improvements to documentation), but I'm curious if workdir input would still be relevant?

Especially if docker/buildx#1028 is resolved, I think we should take into account that changing all relative paths now (via working directory change as a workaround) will not provide the expected consistency intended from context (you fix one issue and regress by introducing another, which workdir is at least clear why).

That said, I know you've also considered to address the separate consistency concern with Docker Compose when the Bake definition is a Compose file. If users were to want similar (while others have valid reasons for avoiding that), consider what an opt-in/opt-out option might be in the docker bake CLI, so that it wouldn't conflict with the decision here.

For the most part, it seems like a context input would only influence the context target fields with a prefix (if the value is a relative path), and maybe the search path of default docker-bake.hcl (docker build doesn't use context for explicit --file paths, I assume it's the same with the docker/build-push-action).

[polarathene]

Reference: build-push-action context input:

Build's context is the set of files located in the specified PATH or URL (default Git context)

---

This should be better clarified for bake-action, since it's not a single build context for a Dockerfile to use? (affecting instructions like COPY/ADD)

When I use docker bake I don't need to provide context at the CLI like with docker build, that is instead handled per target (defaulting to .), similar to how both docker bake and docker build default to Dockerfile too.

Except with the working directory changed, the resolution of all relative paths would also be adjusted, there is no equivalent of docker build --file Dockerfile ./docker-context (despite the docs presently saying dockerfile target field is equivalent to --file, unless using an absolute path), only the implicit default with relative paths prepending the context target field (which would allow traversal up directories via ../).

There is no equivalent feature in the CLI to what this bake-action option is doing (but has been proposed since March 2022):

Docker Bake CLI help text

$ docker bake --help

Usage:  docker buildx bake [OPTIONS] [TARGET...]

Build from a file

Aliases:
  docker buildx bake, docker buildx f

Options:
      --allow stringArray      Allow build to access specified resources
      --builder string         Override the configured builder instance (default "default")
      --call string            Set method for evaluating build ("check", "outline", "targets") (default "build")
      --check                  Shorthand for "--call=check"
  -D, --debug                  Enable debug logging
  -f, --file stringArray       Build definition file
      --list string            List targets or variables
      --load                   Shorthand for "--set=*.output=type=docker". Conditional.
      --metadata-file string   Write build result metadata to a file
      --no-cache               Do not use cache when building the image
      --print                  Print the options without building
      --progress string        Set type of progress output ("auto", "none",  "plain", "quiet", "rawjson", "tty"). Use plain to show container output (default "auto")
      --provenance string      Shorthand for "--set=*.attest=type=provenance"
      --pull                   Always attempt to pull all referenced images
      --push                   Shorthand for "--set=*.output=type=registry". Conditional.
      --sbom string            Shorthand for "--set=*.attest=type=sbom"
      --set stringArray        Override target value (e.g., "targetpattern.key=value")

The closest workaround via the CLI is to use --set *.context=some/path/here, which replaces that context entirely for all selected targets, rather than adjusting the working directory to affect relative path resolution (aka equivalent --workdir feature).

[polarathene]

Given the above and the behaviour differences of docker bake (target options delegated to bake config / --set) vs docker build CLI:

• The workdir input is definitely a bit of a workaround when you're only interested in adjusting the context target field, but may still have some value:
  • If you expected a local outputs/cache-to/cache-from to be relative to some other location (perhaps invoking the action multiple times, or some variable to select a different bake config).
  • The Bake docs also discuss the working directory in regards to remote bake definitions when using cwd:// for context/contexts, so it's a valid concern there too.
  • I haven't considered if that applies to cwd:// for the files input (which Bake docs also mention for use with metadata-action), but this PR doesn't adjust behaviour in how the action resolves such anyway?
  • Does it actually make sense to drop workdir?
• Changing source to context, with the included functionality of workdir input for local contexts (until this is better supported by docker bake upstream) still seems relevant (providing a UX benefit of consistency for expectations between docker/bake-action and docker/build-push-action).

---

Perhaps something like this? (I haven't aligned the final |):

Suggested change

	| `context` | String | Context to build from. Can be either local to specify the working directory or a [remote bake definition](https://docs.docker.com/build/bake/remote-definition/) |
	| `context` | String | Sets the Bake context which all relative paths use as the working directory. Can be assigned a local path ([Path context](#path-context)) or [remote bake definition](https://docs.docker.com/build/bake/remote-definition/) ([Git context](#git-context)) |

I'm not sure how accurate that is with regards to cwd:// for git context, but looking at the PR it seems the context set here results in changing the working directory for git contexts too?

I think that it should also clarify that expectation of target fields context influencing the relative path of the dockerfile, but as that gets verbose for the inputs descriptions maybe introduce a "Bake Context" section header, with "Git Context" + "Path Context" sections under that?

Then this input description can just link directly to that, and describe:

• The working directory from the context input affecting relative paths.
• The context + dockerfile target fields behaviour.
• The implicit default {{defaultContext}} (further expanded on in the "Git Context" section), and explicit Path / Git contexts.
• Git context section including the remote bake definition link, which it presently doesn't.

That'd provide this terser description which is what the user cares about (_link for more details on what bake context is + what default to expect.

Suggested change

	| `context` | String | Context to build from. Can be either local to specify the working directory or a [remote bake definition](https://docs.docker.com/build/bake/remote-definition/) |
	| `context` | String | Sets the [Bake context](#bake-context). Uses [`{{ defaultContext }}`](#git-context) by default. |

[polarathene]

Other than that, you may want to hold off if you can resolve the relevant CLI issue in a timely manner first, considering that workdir input still seems relevant and that context should perhaps only be focused on affecting the resolution of the context target fields base path (which likewise influences the dockerfile field resolution)?

Reasoning:

• docker build CLI differs from docker compose build / docker bake CLI, where docker/build-push-action can set the build context of a Dockerfile (and it's default location), but override that with a relative path via --file unaffected by the context. Docker Compose and Docker Bake don't support such AFAIK and would require absolute paths.
• It seems that there is a valid expectation for the working directory to be distinct from the build context.
  • docker build args like --output and --cache-[from|to] can use paths releative to the CWD.
  • This is also what Docker Compose does, but this PR's context input for docker/bake-action would not be consistent in the same manner as the equivalent input for docker/build-push-action.

context input vs workdir input functionality:

• The context target field using a path relative to the Bake definition would ideally be resolved as part of docker/buildx#1028 (which will probably break existing workarounds, but become consistent with docker compose build)
• Other than addressing the context target field, this input only seems relevant for the files input? (If considered similar to docker build context for the default Dockerfile file location)

---

My understanding of docker/buildx#1028 is the "Bake context" expectation is to favor relative path resolution from where the Bake definition (eg: docker-bake.hcl, compose.yaml) is located (the first file if overrides are provided), but all discussion there has been focused on context / dockerfile target fields with regards to Docker Compose specifically.

• I've confirmed that the Docker Compose setting build.cache_to (instead of build.x-bake.cache-to) resolves it's relative path to the CWD just like Docker Bake.
• Similarly Docker Compose treats it's build context field the same way with dockerfile as Docker Bake does, so no difference there.
• If compose.yaml only sets a path as the value to build, that becomes the context and implicit Dockerfile is used at that context location. Same as with Docker Bake, just a relative path resolution difference (from file vs from CWD).

Thus it seems the only relevant difference with how Docker Compose is handling paths applicable to Docker Bake is for how the context base is adjusted.

[crazy-max]

@polarathene Thank you for the detailed review, appreciate the time you put into outlining the nuances around Bake context resolution, relative paths, and the current upstream behavior.

I will clarify a few core points to better explain the intent of this PR and how it fits within existing Bake capabilities and constraints.

The primary motivation is to remove the long-standing ambiguity between:

• workdir (local working directory override)
• source (Git/remote bake definition)

Both inputs attempted to answer the same question: "Where should Bake run from?", but used different naming, different semantics, and frequently confused users. Aligning this with docker/build-push-action context makes the behavior significantly more predictable.

To avoid conflating this with the Bake "context" target field, the PR explicitly describes the input as:

• Path context (local directory → used as working directory for evaluating bake definition)
• Git context / remote bake definition (same behavior as today's source)

This isn't redefining how upstream Bake interprets target contexts; it's unifying the entry point that the action uses before invoking Bake.

You are correct that docker bake currently does not expose a CLI-level working-directory override comparable to:

docker build --file Dockerfile ./context

This gap is exactly why workdir existed originally and why context needs to preserve its functionality until upstream implements something equivalent (see docker/buildx#1028).

The action must provide a way to run Bake from a subdirectory:

      -
        name: Build and push
        uses: docker/bake-action@v6
        with:
          context: ./subdir

This mirrors the original purpose of workdir. It doesn't try to reinterpret Bake's own target context semantics.

The closest workaround via the CLI is to use --set *.context=some/path/here, which replaces that context entirely for all selected targets, rather than adjusting the working directory to affect relative path resolution (aka equivalent --workdir feature).

It would only work if every target's context is meant to be replaced, and the user also manually points files: to the correct bake definition:

      -
        name: Build and push
        uses: docker/bake-action@v6
        with:
          files: ./subdir/docker-bake.hcl
          set: |
            *.context=./subdir

This modifies the bake definition itself, not the working directory. It doesn't provide a general mechanism for running Bake from a subdirectory.

By contrast:

      -
        name: Build and push
        uses: docker/bake-action@v6
        with:
          context: ./subdir

simply makes the action evaluate the bake definition exactly as if the user had executed:

cd ./subdir
docker bake

This is the behaviour users expect today from workdir, and the PR provides the same outcome via the unified context input.

Given the discussion above:

• The new context input already subsumes workdir functionality for local directories.
• Retaining both would preserve the confusion this PR is intended to eliminate.
• Upstream will eventually provide official semantics for resolving paths relative to bake definitions buildx bake: Specifying --file in another directory leads to failure buildx#1028, but until then, the action must expose a consistent UX for running Bake in a subdirectory.

So the removal is intentional and simplifies the API without reducing functionality.

Although I agree with your point that the documentation should explicitly distinguish:

• Bake Action context (working directory or Git reference)
• Bake target context fields (per-target build context)
• How relative path resolution behaves depending on local vs Git context

I will update the docs accordingly, and your suggested shorter table description fits well once that section is added.

[polarathene]

TL;DR

It seems better to delay this PR until resolved upstream, otherwise keep workdir and just change source to context for the time being.

The Git context is the expected behaviour for what the context input should accomplish. The Path context should reach parity first IMO, rather than introduce it into the action with the same temporary workaround that adjusts the working directory? (full concerns for users and maintainer perspectives given below)

Pragmatically I agree with you and so long as documentation covers what to expect when using context with a value beyond ., you're doing the best to align expectations within the scope of this action 👍

---

Full response

I've provided this workflow to demonstrate where Path context fails (unrelated to this PR) with the present workaround to change the working directory.

I later express why a new context input may better be served when it's possible to do docker bake --context path/to/use as a search path for Bake definition files and the relative ./ context to prepend, just like remote context is already doing in both cases.

Comparison between Bake Action (v6) and Build Push Action

.github/workflows/example.yml:

name: Example

on:
  workflow_dispatch:

jobs:
  bake-remote:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build with remote context (Git)
        uses: docker/bake-action@v6
        with:
          source: "{{ defaultContext }}:bake-action"
          files: ./docker-bake-x.hcl

          # NOTE:
          # - For Docker Compose projects it's expected that their `build.context` relative path is from the location of the config.
          # - For Docker Bake configs the relative path for target `context`/`build-contexts` fields is the current working directory.
          # - Thus the below settings would fail in this case for local Path Context, but for remote Git Context (as above) with a subdir
          #   context is managed as expected without adjusting the working directory.
          #source: "{{ defaultContext }}"
          #files: ./bake-action/docker-bake-x.hcl

          # Likewise `workdir: ./bake-action` would only work if you do not expect the parent directory to be available for
          # - Referencing files via `cwd://`
          # - Other relative paths unrelated to the build context, such as `type=local` and cache import/export
          #source: "{{ defaultContext }}"
          #workdir: ./bake-action
          #files: ./docker-bake-x.hcl

      - run: ls artifacts

  bake-local:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build with local context (Path)
        uses: docker/bake-action@v6
        with:
          # The proposed `context` input for Path context intends to unify these two inputs from v6:
          source: .
          workdir: ./bake-action
          # Setting the `workdir` does resolve custom config filenames similar to Git context,
          # by not requiring a subpath prefix, however the the `cwd` build-context will now fail.
          files: ./docker-bake-x.hcl

      # This will fail due to working directory change, actual location is now `./bake-action/artifacts`:
      - run: ls artifacts

  bpa-remote:
    runs-on: ubuntu-latest
    steps:
      # Only required for added local `cwd` context:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build with remote context (Git)
        uses: docker/build-push-action@v6
        with:
          context: "{{ defaultContext }}:build-push-action"
          # Resolved relative to the context (which must be set for it's relative COPY to work)
          file: ./Dockerfile-x
          # Local working directory context:
          # (This action (or equivalent upstream support rather) does not understand `cwd://`; just use `.`)
          build-contexts: cwd=.
          outputs: ./artifacts/

      - run: ls artifacts

  bpa-local:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build with local context (Path)
        uses: docker/build-push-action@v6
        with:
          context: build-push-action
          # Unlike with remote Git context, the Path context requires an explicit
          # relative path when the filename doesn't match the default `Dockerfile`:
          file: ./build-push-action/Dockerfile-x
          build-contexts: cwd=.
          outputs: ./artifacts/

      - run: ls artifacts

./bake-action/docker-bake-x.hcl:

target "default" {
  contexts = {
    cwd = "cwd://"
  }

  dockerfile-inline = <<-HEREDOC
    FROM scratch
    COPY --link ./hello.txt /
    COPY --link --from=cwd README.md /
  HEREDOC

  output = ["./artifacts/"]
}

./build-push-action/Dockerfile-x:

FROM scratch
COPY --link ./world.txt /
COPY --link --from=cwd README.md /

Hopefully that illustrates how even with context input, forcing the working directory change as a workaround (until resolving the issue upstream) introduces it's own problems.

• docker/bake-action: can only successfully build the project with the Git context.
• docker/build-push-action: is capable of building successfully with both Git and Path contexts.

EDIT: Yet pragmatically.. this kind of problem is unlikely I guess. I understand the motive to unify on a context input; where if upstream doesn't resolve the issue in a timely manner, the concerns I've raised here are perhaps a worthwhile tradeoff 🤔

Git Context

Using Git context demonstrates Docker Bake is capable of solving this concern without requiring a change to the working directory.

It correctly applies the relative context path only to each targets build context + dockerfile (everything else continues to use relative paths from the working directory like would be expected).

• This also aligns with context resolution for Docker Compose (As per my earlier feedback with comparison to Docker Compose behaviour):
  • Only the build.context setting was resolved relative to the compose.yaml location (and build.dockerfile relative to build.context).
  • Other relative paths related to build configuration (not just build.x-bake.*) use the working directory instead.
• Similar to docker/build-push-action, when using a remote context the --file arg is relative to that context subdir (unlike with Path context where that would need to be repeated). A remote Dockerfile / Bake definition can also be used by referencing that specifically via --file while using a local context.

workdir vs context inputs

Regarding the referenced issues in the PR description:

• The original issue that motivated workdir input for this action, and the related upstream buildx issue (and discussion there) was specifically for a Docker Compose config expectations (relative build.context path resolving from the file location).
• These two issues cited were about encountering breakage from the default context being switched from Path to Git with the v6 release of the action:
  • Workdir does not work or is not documented properly #294 (comment)
  • Bad context on version 6.x.x #301 (comment)
• The remaining issue ref was regarding confusion of the source input name (with how it only supported . to imply local/path based context, effectively cwd:// like shown with docker/build-push-action).
  • Rather than a working directory change, the expectation there was to better align to the context input of docker/build-push-action for controlling Path vs Git contexts instead of source input.
  • That change alone is separate from the workdir (workaround) concern. As noted, the context input should only be influencing the relative path resolution for each targets context field.

Setting workdir input is predictable (same behaviour regardless of Path or Git context for cwd://) and tied to the action release. Making that functionality implicit with a context input however may lead to similar confusion referenced above from the v6 release? (once the upstream concern is resolved, which would not have the release associated to the version of this action)

Once the upstream issue is resolved, context would ideally search files input from that provided context path, probably via some CLI option like --context or heuristic (Docker Compose files) to toggle the relative context path resolution behaviour.

No directory change should be required with this approach but while the context input itself would not change for the user of the action.. when a compatible version of Docker Bake is available, the other relative paths resolved (outputs / cache) suddenly would, and now your action needs to maintain (and document / support) both variations of a context input since the action version is unrelated to the Docker Bake version used.

---

Original write-up

Collapsed for brevity

This covers roughly the same points before I revised/expanded into the variant above (No AI tooling used).

You are repeating a lot of what I've already brought up, I'm not sure if that was summarized by an AI tool (no offense, I give that impression sometimes despite how much time I sink into these write ups 😅)

Please take this into consideration before you decide to merge in advance of Docker Bake upstream issue being resolved.

The existing workdir input is clearer in intent as opposed to the proposed context input:

• It changes working directory as name implies and also applies to both context modes (Path / Git). This is not so obvious from a context input.
• docker/build-push-action doesn't change the working directory for it's context input, it's only interested in defining the build context of a single build target, unlike Docker Bake and Docker Compose. This difference is relevant for properly supporting other build related options (such as outputs and cache import/export).

If you decide that the context input should set the working directory for Docker Bake:

• This will have a similar UX to docker/build-push-action but it won't be aligned in functionality (--output ./artifacts will be at context path, as will --cache-from / --cache-to).
• docker/bake-action differs in that it can have multiple targets, only the base path of the context could be adjusted (and is planned to adopt file-based behaviour like Docker Compose has).
  • One may expect the context input instead only alters this base path via some future arg that Docker Bake lands (which is probably simpler to implement support for than the implicit file-based context resolution that Docker Compose uses?). This would better align with docker/build-push-action.
  • I do understand the overlap when it comes to using context to resolve Dockerfile implicitly in docker/build-push-action, and how you may prefer that for resolving docker-bake.hcl implicitly. However:
    • When the default file name here changes for docker/build-push-action (just like with docker build --file ... <context> that calls out to), the Dockerfile is no longer appended to the context input path (only when using Git context).
    • That should be no different with either actions {{defaultContext}} expression (shared functionality for an implicit git context URI based on the workflow github context metadata).
    • There is no equivalent {{context}} expression helper for an input to reference the context input when using Path context, so repeating the context input value or relying on the implicit docker-bake.hcl or similar is necessary.

---

Direct replies

The primary motivation is to remove the long-standing ambiguity between:

* `workdir` (local working directory override)

* `source` (Git/remote bake definition)

Both inputs attempted to answer the same question: "Where should Bake run from?", but used different naming, different semantics, and frequently confused users. Aligning this with docker/build-push-action context makes the behavior significantly more predictable.

To avoid conflating this with the Bake "context" target field, the PR explicitly describes the input as:

* Path context (local directory → used as working directory for evaluating bake definition)

* Git context / remote bake definition (same behavior as today's `source`)

This isn't redefining how upstream Bake interprets target contexts; it's unifying the entry point that the action uses before invoking Bake.

I'm all for that, and for the Git context it works well. Technically it's good for the Path context in common cases, but I still have a concern with the working directory being changed. I understand why it's done as a workaround, I'm just not fond of the influence beyond the targets context paths being affected.

That said, it's not going to be an issue for anyone using a bake definition at the repo root dir, nor are users likely to have much issue with the broken Path context workflow I provided (they'd just adjust the paths as needed or switch to Git context).

Pragmatically I agree with you and so long as documentation covers what to expect when using context with a value beyond ., you're doing the best to align as you can 👍

The action must provide a way to run Bake from a subdirectory:

      -
        name: Build and push
        uses: docker/bake-action@v6
        with:
          context: ./subdir

This mirrors the original purpose of workdir. It doesn't try to reinterpret Bake's own target context semantics.

Yet you do not adjust the working directory in docker/build-push-action, only the build context. In that sense the two inputs serve different purposes.

With proper context support upstream, the need to adjust the working directory itself would be reduced but it could still be leveraged if the Bake definition intends to be run from that child directory with correct semantics. I have demonstrated that even Docker Compose only adjusts the build context path, it respects the working directory for other paths which is the semantics one would typically expect.

I imagine it's less likely with docker/build-push-action given these are configured via the action, while for Docker Bake / Compose it's configured within their config/definition files. You can always bring back workdir in that case if there's demand for it, once the main concern with context path resolution is resolved upstream.

---

This is the behaviour users expect today from workdir, and the PR provides the same outcome via the unified context input.

I can understand the expectation for workdir, but not with context implicitly adjusting the working directory. A context input has a different meaning associated to it.

Adjusting the working directory will work for simpler use-cases as a workaround where all files live in a child directory, but it will also force outputs/cache into that location which I doubt users expected if coming from docker/build-push-action.

This concern only applies to Path context, Git context doesn't run into the problem (assuming bake definitions and relative base context should be co-located, since this is affected by --file for Git context with subdir path).

---

The new context input already subsumes workdir functionality for local directories.

Yes, but you might as well switch to context when changing the working directory isn't required.

• I have compared the proposed context input for this action to what the UX is like with docker/build-push-action and am concerned about pushing this input change too eagerly.
• You're already aware of minor burden from the default context mode change to align with docker/build-push-action, I worry that this context input changing in behaviour would be worse (and potentially annoy users of the action that had already migrated for v6, to this for v7, and potentially again for v8 due to subtle changes they must grok).

Retaining both would preserve the confusion this PR is intended to eliminate.

Defer introducing context then, as that sounds even more confusing if it's undecided how the solution in Docker Bake upstream will be resolved. I chimed in on the upstream issue, and in this response express concern if a --context or similar option would be introduced (possibly that's a more straight-forward fix to implement for the time being).

Ideally the context input would match semantics of docker/build-push-action like intended, not partially. I've demonstrated how this is already in a good state for Git context but without an upstream solution for Path context, this familiarity seems like it'd just muddy the waters further for any user confusion. workdir is more explicit in intent until context can work as intended.

Upstream will eventually provide official semantics for resolving paths relative to bake definitions

If you're comfortable with the disparity between Git vs Path context (as the workflow example demonstrates), and any future change to adapt to upstream semantics being addressed, go for it.

I'm just raising concerns to save everyone time from migration churn and caveats of familiar context input that exhibits inconsistencies between the two actions and contexts (specifically Path context of docker/bake-action).