Introduction

If the code you want lives on a branch other than the repository’s default branch, Docker can still build it directly. The important part is choosing whether you are doing a local build from a checked-out branch, a remote Git build context, or a Docker Hub automated build tied to a branch rule.

The Simplest Option: Check Out the Branch Locally

The most predictable workflow is to clone the repository, switch to the branch you want, and build from the local directory.

1git clone https://github.com/example/myapp.git
2cd myapp
3git checkout feature-login
4docker build -t myapp:feature-login .

This is easy to debug because you can inspect the exact files that Docker sees. It is also the safest approach when the build depends on local secrets, submodules, or generated files.

Build Directly From a GitHub Branch

Docker can also use a remote Git repository as the build context. To target a non-default branch, append a Git URL fragment.

docker build -t myapp:feature-login \
  https://github.com/example/myapp.git#feature-login

That tells Docker to clone the feature-login branch and use it as the build context.

If the Dockerfile lives in a subdirectory, include that as well:

docker build -t myapp:feature-login \
  https://github.com/example/myapp.git#feature-login:docker

In that example, feature-login is the branch and docker is the subdirectory used as the build context.

When to Prefer Local Versus Remote Builds

A remote Git context is convenient in CI or in quick experiments, but it is less transparent than a local checkout. A local checkout is usually better when:

• you want to verify the exact commit before building
• the repository uses private submodules or private dependencies
• you need to patch files before the build
• you want to use normal Git inspection commands during debugging

A remote Git context is useful when:

• the build should be a one-liner
• the repository is public
• you want the build host to fetch the branch directly

Docker Hub Automated Builds

If you mean Docker Hub autobuilds rather than the docker build command, the answer is different. Docker Hub uses build rules that map a source branch or tag to an image tag.

In that setup, you do not hard-code master or main into the Dockerfile. Instead, configure the build rule so that pushes to a branch such as feature-login trigger a build for a chosen image tag.

A practical example is:

• source branch: release-2026
• output image tag: staging

That lets Docker Hub build from a non-default branch automatically whenever that branch receives a push.

Private Repository Considerations

If the GitHub repository is private, authentication matters. Local builds are easiest because Git already handles access once the repository is cloned.

For direct remote Git builds, use supported authentication such as SSH forwarding or build secrets when the builder supports them. Do not pass tokens as plain build arguments if they are only needed to fetch the repository.

Common Pitfalls

The most common mistake is forgetting that a remote Git build context uses the repository contents from that branch, not whatever local edits you have sitting on disk.

Another issue is assuming the fragment after # is always a branch. Docker also accepts tags and some other Git refs, so make sure the name points to the ref you actually intend.

A third problem is building from a branch when the Dockerfile is not at the repository root. In that case you must specify the subdirectory or build locally from the correct folder.

Summary

• The simplest solution is to check out the desired branch locally and run docker build ..
• Docker can build directly from a GitHub branch with repo.git#branch syntax.
• Add :subdir if the build context is not the repository root.
• Docker Hub autobuilds use branch-based build rules rather than local CLI syntax.
• For private repositories, prefer authenticated local checkouts or secure Git-context authentication.