Jan Mikoláš
Glossary
Build
A build prepares one specific application version for testing or release. It is not always compilation, and it is not automatically deployment to production.
Short definition
A traceable artifact comes from sources, not a folder “somewhere on a developer’s machine”.
For some languages, a build includes compilation into a binary. In PHP, it often installs exact dependencies from composer.lock, generates an autoloader, and checks code. Frontend TypeScript is commonly translated to JavaScript in a conventional build, with CSS built too. The result can be a deployment-ready directory or a container image. Even without classic compilation, this is a build when the process prepares repeatable output.
A build is not deployment. A build creates an artifact; deployment transfers or activates it in a specific environment. It is not normal runtime either: the runtime executes the artifact. Keeping these steps separate lets a team test one version and promote the same verified artifact to staging or production without rebuilding it in CI/CD.
What it solves
The same output for development, CI, and release
A build removes manual steps and uncertainty about what was actually checked and released.
- installing PHP dependencies from the version recorded in composer.lock
- creating optimized frontend assets or other distributed files
- building a Docker image with a clear tag or digest
- running checks in a clean environment before an artifact exists
- passing one verified artifact between CI, staging, and production
Practical example
A PHP application as a container artifact
CI takes a specific commit, installs production Composer dependencies from the lock file, runs checks, and builds an image tagged with the version. The base image, Composer files, and source code are explicit inputs. The resulting image is an artifact that can be inspected and stored in a registry before deployment.
Secrets do not belong in the build context or image. A database password, API token, or production certificate is supplied only at runtime through the target environment mechanism. If a build needs a secret to download a private dependency, pass it temporarily through a secure build mechanism, not in a Dockerfile or image layer.
Dockerfile
FROM composer:2 AS dependencies
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --prefer-dist --no-interaction
FROM php:8.4-cli
WORKDIR /app
COPY --from=dependencies /app/vendor ./vendor
COPY . .Build diagram
Source code → verification → artifact → deployment
Build diagram: commit and lock files → clean build environment → checks and creation → versioned artifact → separate deployment. The final step is no longer a build.
- Specified inputs A specific commit, lock files, build scripts, and versioned configuration state what to create. Unknown local files must not silently change the output.
- Clean environment CI or a container starts without leftovers from manual work. The PHP, Composer, and other tool versions are part of reproducibility.
- Verify and build The process installs locked dependencies, runs relevant checks, and creates distributable files or an image.
- Artifact The output gets a version or digest, is stored in a designated location, and can be linked to a commit and check results.
- Deployment Only a separate step deploys the artifact with the target environment configuration and secrets. A successful build does not prove successful operation.
Practical boundaries
A build composes tools, but must not hide their inputs.
A build command can look simple, yet the versions, dependencies, and responsibility for its output must stay readable underneath.
Composer
Installs exactly locked PHP dependencies and creates an autoloader. A general composer update is not the usual step of a reproducible production build.
Docker
A build creates an image from a Dockerfile and context. Limit the context with .dockerignore so it does not contain secrets, local caches, or unnecessary large files.
CI/CD
CI often builds and tests an artifact. CD can promote and deploy it; a green job does not replace target-environment monitoring.
IDE and CLI
An IDE or local CLI can start a build. The build rules must remain versioned and work on a clean runner too.
Important distinctions
Build, compilation, artifact, and deployment have different responsibilities.
When a team names these boundaries, it can more easily trace the difference between a code change, output preparation, and a problem after deployment.
Build
The whole repeatable preparation of an output. It can include downloading dependencies, generating code, assets, tests, or image creation.
Compilation and TypeScript
Compilation translates source code into another form, often a binary program. It is only one possible build step; a common PHP build does not need it. A TypeScript build often translates .ts to JavaScript and can generate assets or declarations.
Artifact
A specific build output: archive, package, binary, asset bundle, or Docker image. It should be traceable and immutable.
Deployment
Transfer and activation of an artifact in a target environment. It works with configuration, migrations, health checks, and runtime secrets, so it is a separate step.
Reproducibility
The same declared inputs create the same or equivalent output. This helps when fixing an incident and safely reviewing updates.
Benefits and limits
Reproducibility needs exact inputs and discipline around outputs.
Benefits
- a traceable relationship between commit, checks, and released artifact
- less difference between local verification, CI, and deployment
- ability to promote the same artifact without rebuilding
- faster diagnosis of what actually reached production
Risks and mistakes
- a build depending on an uncommitted local file cannot be reliably repeated
- secrets in an image, artifact, or cache can reach a registry or logs
- a latest tag without a specific version makes rollback and tracing harder
- rebuilding for production can introduce a different dependency than the tested artifact
- a successful build does not check migrations, networking, runtime configuration, or production behavior
When it makes sense
Every deployed application needs at least a small repeatable build.
A simple PHP project may have a build consisting of dependency installation from composer.lock and tests. An application with a frontend, containers, or more services needs more steps. The scope should match risk, but the process must not depend on what happens to be installed on one developer machine.
A build does not solve business rules, database backup, access control, or rollout. For order and payment changes, artifact work must be accompanied by compatible migrations, environment configuration, monitoring, and a safe return path.
What to keep in mind
An artifact should be small, traceable, and free of secrets.
A good build pipeline shows what created the output, how it passed checks, and where it can safely go next.
- tie a build to a specific commit and lock files, not floating “latest” dependencies
- use a clean or isolated build environment with specified tool versions
- give the artifact a version or digest and retain its provenance
- keep secrets, private keys, and production configuration out of build context, image, cache, and logs
- limit Docker context with .dockerignore and review multi-stage builds
- promote the same verified artifact to later environments rather than rebuilding for every deployment
Frequently asked questions
Build without common mix-ups
Is a build always compilation?
No. Compilation is one possible step. A PHP build often installs dependencies, creates an autoloader and assets, or builds an image without translating PHP into a binary program. A TypeScript frontend, by contrast, is often translated from .ts to JavaScript during its build.
Is build the same as deployment?
No. A build creates an artifact. Deployment activates it in a specific environment with runtime secrets, migrations, configuration, and operational verification.
Why not build again on the production server?
Tool versions, network access, or floating dependencies can make a different output. Promoting one verified and identified artifact is safer.
Can secrets go into a Docker image if the registry is private?
No. An image can be copied, cached, or scanned, and a secret may remain in a layer or log. Secrets belong in a secure runtime mechanism of the target environment.
How I maintain change quality
I want the build, checks, and released artifact to be traceable as one whole.
For PHP applications, I connect Composer, containers, and quality gates so every version is buildable, verifiable, and safely prepared for the next step.