ONBUILD registers an instruction that runs later, when another Dockerfile uses your image in its FROM line. The trigger runs as if it were placed right after that FROM. It can be handy, but it hides work from reviewers, so most teams are better off with explicit stages.
How it works
The Dockerfile reference describes the rules. A trigger is stored in the image. When a downstream build uses that image as its base, triggers run in the order they were registered. If one fails, the downstream build fails. Triggers are cleared from the resulting image, so they do not pass on to grandchild images. ONBUILD ONBUILD is not allowed, and ONBUILD cannot trigger FROM or MAINTAINER.
ONBUILD COPY . /app
ONBUILD RUN make
A team that builds from this base gets a copy and a make step added automatically.
Why it is a risk
| Issue | Effect |
|---|---|
| Hidden behavior | The downstream Dockerfile does not show what runs |
| Surprise inputs | A trigger may copy the whole build context, including files you did not mean to ship |
| Trust | You run instructions chosen by whoever built the base image |
| Review gaps | Static checks of the downstream file miss the trigger |
The trust point is the important one for security. If you pull a base image from outside your organization, an ONBUILD trigger runs inside your build, with your build context and any secrets you mounted. You can inspect an image for triggers with docker inspect and look at the configuration for an on build field before you use it.
Alternatives
- A shared base image with no triggers, plus a documented Dockerfile template in each repository.
- A multi-stage Dockerfile where the steps are written out. See build targets.
- A build tool or CI template that runs the same steps and is code reviewed.
Each puts the behavior where a reviewer can read it.
If you do use it
Keep triggers to a minimum, document them in the base image README, restrict the base image to your own registry, and test downstream builds in CI. Avoid triggers that copy the entire context, and list them in your image inventory so owners know the base has them.
Checking third party bases
Before adopting a base image, inspect its configuration for triggers, read its Dockerfile source if published, and check that its builds are reproducible. A scan of the final image will not reveal a trigger, since triggers clear after they run.
Quick check
Do ONBUILD triggers appear in the final image?
No. They are cleared from the resulting image, so they run once in the build that uses the base.
How can I see triggers in an image?
Inspect the base image configuration and look for the on build entries before you build from it.
Safeguard
Safeguard does SBOM and dependency scanning, and its policies and gates can run in CI so a bad image does not reach production. You can try a free scan before deciding anything.
Sources
Last reviewed: 19 October 2026.
