Choose how your app is built
There is one decision, and it is the Dockerfile path in your ’s build settings. Leave it empty, the default the dashboard calls Automatic (no Dockerfile), and we detect your language and toolchain from the root directory and build it for you. Set a path and we run a normal Docker build with that file, using the root directory as the build context. See Dockerfile builds. To get an automatic build right:- Pin your tool versions in the files your ecosystem already uses. Detection reads them to decide which toolchain to install, so a project that pins nothing can move versions underneath you between builds.
- In a monorepo, set the root directory to the app’s own directory, so detection looks at the right project rather than the repository root.
- Set a build command when the detected one is wrong. It can be up to 1000 characters, and it is ignored when a Dockerfile is set.
Why your build is waiting
A workspace runs one build at a time on every plan today, so a second deployment sits inpending until the first finishes. Deployments from a prebuilt image queue too, even though they don’t build.
Production deployments jump ahead of preview deployments in the queue, so a hot-fix doesn’t wait behind a backlog of pull request builds.
A deployment that has waited an hour for its turn fails rather than waiting longer, so a jammed queue surfaces instead of hanging. Deploy again once the queue has drained.
Why your build failed
A failed build ends the deployment asfailed with the error code build_failed. Read the build output on the deployment’s detail page in the dashboard, where it streams live and stays afterwards. Common causes are rewritten in plain language above the log, for example a Dockerfile that couldn’t be read or a file the build referenced that doesn’t exist, and the full log is always underneath.
Problems in your own source, such as a Dockerfile syntax error or a build command that exits non-zero, fail immediately. Retrying them without changing anything gives the same result.
Infrastructure blips are retried for you, up to five attempts and no longer than 30 minutes in total, whichever comes first. A build that takes unusually long and then fails has normally spent that time in retries.
Make builds faster, or skip them
Build layers are cached per project, up to 25 GB, with layers older than 7 days evicted. Repeat builds of a project whose dependencies haven’t changed reuse that cache. A project you haven’t deployed in over a week builds from scratch again. Because every deployment produces its own image, promoting and rolling back never rebuild. They run an image that already exists, which is why a rollback is fast. Two settings stop a push from building at all:- Watch paths builds only when a changed file matches one of the environment’s glob patterns, so a documentation-only commit doesn’t start a build.
- Auto deploy, turned off, stops pushes from deploying entirely, leaving you to deploy from the dashboard or the API when you choose.
skipped deployment with the reason, so you can tell the difference between a push we ignored and one we never saw. Both settings live on Build settings, and the order they’re evaluated in is on GitHub integration.
Your environment variables are available while the build runs without being baked into the image. See Build-time secrets.
Next steps
Dockerfile builds
Take control of the image when detection isn’t enough.
Build-time secrets
Use environment variables during the build without baking them into layers.
Build settings
Root directory, Dockerfile, build command, watch paths, auto deploy.
Deployments
Where the build sits in the deployment lifecycle.