How to Set Up a Bamboo CI/CD Pipeline for PHP Projects
Build a Bamboo pipeline for PHP with agent setup, Composer checks, build artifacts, deployment stages, and practical troubleshooting.
A Bamboo CI/CD pipeline for a PHP project connects a repository to a build plan that runs the checks your project requires, then makes successful build output available to a deployment plan. The agent must have the PHP and Composer tools your project requires. A practical flow is commit → checkout → install dependencies → run checks → publish required output → deploy.
The exact Bamboo task configuration depends on your Bamboo release, agent operating system, PHP and Composer constraints, repository, and deployment target. The Atlassian references below document Bamboo Data Center capabilities and patterns; they do not provide a current PHP compatibility matrix or a validated end-to-end PHP recipe. Treat the example commands as a starting point and verify them against your project and installed Bamboo version.
1. Confirm your environment
Before creating the plan, write down the versions and deployment assumptions the pipeline must satisfy. Bamboo Data Center documentation is not a guarantee that a particular agent image or PHP runtime is supported by your installation.
- Bamboo edition and release.
- Agent operating system and whether the plan uses a local or remote agent.
- The PHP version or version range required by
composer.json. - The Composer version and dependency installation policy used by the project.
- Required extensions, system libraries, and services for tests.
- Whether tests need a database, credentials, or other external services.
- Deployment destination, credentials mechanism, release policy, and files needed to deploy.
Check these values against the actual agent and repository. The PHPUnit versions listed in Bamboo’s agent-capability documentation are examples of executable capabilities, not evidence of compatibility with a current PHP application. [Atlassian’s agent capability reference](https://support.atlassian.com/bamboo/kb/list-of-default-keys-for-the-bamboo-capabilitiesproperties-file/) describes capabilities available to agents.
2. Prepare the Bamboo agent
The agent executes the plan’s work. Install or otherwise provide the project’s required PHP runtime, Composer, extensions, and any test or deployment tools on the agent. Confirm their executable paths and versions under the same account and environment Bamboo uses to run jobs.
Bamboo Data Center supports agent capabilities that identify available executables. Remote-agent capabilities can be configured through bamboo-capabilities.properties; a capability label does not install software or prove its version is suitable. Bamboo’s documented capability examples include PHPUnit, Docker, and Git. [Review the documented capability keys](https://support.atlassian.com/bamboo/kb/list-of-default-keys-for-the-bamboo-capabilitiesproperties-file/).
On a Linux agent, for example, inspect the tools from the agent’s service account:
php --version
composer --version
git --version
Also check required PHP extensions with php -m and compare them with the application and test requirements. If Bamboo cannot find a command that works in your interactive shell, check the agent service’s PATH, working directory, permissions, and configured executable capability.
3. Create the build plan
- Connect the repository and select the branch or branch strategy you want Bamboo to build.
- Configure a repository trigger appropriate to your workflow so changes start a build.
- Assign the plan to agents with the required runtime and tools.
- Add the project checks as Bamboo tasks or run them through a script task.
- Configure the plan to fail when a required command fails, and publish only the output needed by later stages.
Bamboo has native support for build, test, and deployment tasks, and script tasks provide a way to run command-line work. Choose tasks based on what the installed Bamboo version and project need; the official configuration overview does not prescribe a PHP-specific task sequence. [Bamboo Configuration Options](https://support.atlassian.com/bamboo/kb/bamboo-configuration-options/).
Example script for a PHP project
This shell example assumes a Composer project with a lock file and a test script defined in composer.json. It illustrates a command sequence; it is not an Atlassian-validated PHP recipe. Adapt the checks to the scripts and dependencies your project actually defines.
#!/usr/bin/env bash
set -euo pipefail
php --version
composer --version
composer validate --no-check-publish
composer install --no-interaction --prefer-dist
composer run-script test
Save it in the repository, for example as ci/build.sh, and invoke it from a Bamboo script task with bash ci/build.sh. If your project does not define a Composer test script, replace that command with the test runner and arguments your project uses. Add separate lint, static-analysis, or test commands only when the project has them configured.
set -e makes the shell exit when a command fails, and pipefail helps preserve failures in pipelines. This makes a failed required check visible as a failed build, rather than letting later commands mask it.
4. Decide what the build should publish
Identify the exact files the deployment process needs. Depending on the application, that may mean a source checkout, a packaged release, generated assets, or another project-specific output. Do not assume a generic PHP artifact layout: the cited Bamboo references establish the plan-to-deployment relationship but do not define PHP packaging conventions.
Configure Bamboo’s build artifact paths to include the output you have chosen, then configure the deployment project to retrieve that artifact. Keep secrets out of artifacts and source control. Verify that the artifact contains everything deployment needs and excludes development-only files if your release process requires that.
5. Add deployment environments and release controls
Create a deployment project associated with the successful build plan, then configure environments that match your release path, such as a test environment followed by production. The deployment steps themselves depend on the target system and should use the commands and credentials validated for that system.
Bamboo’s documented relationship is that a repository commit can trigger a build plan, which can then trigger a release. Use automatic deployment triggers only where they match your release policy. [Atlassian’s commit-to-deployment reference](https://support.atlassian.com/bamboo/kb/how-to-find-relational-link-between-a-repository-commit-and-deployment-in-bamboo/) describes this relationship.
If you need a human gate, Atlassian documents a manual stage at the end of the source plan followed by a deployment trigger after that stage succeeds. Its article describes this as an approval-like workaround, not a native deployment approval workflow. Confirm the behavior in your Bamboo release before relying on it. [See the documented manual-stage approach](https://support.atlassian.com/bamboo/kb/implement-an-approval-workflow-for-deployments-in-bamboo/).
6. Choose UI configuration or Bamboo Specs
A UI-configured plan can be straightforward when the team manages a small number of plans directly in Bamboo. Bamboo YAML Specs can represent plans and deployments as configuration in a repository, which may suit teams that want their pipeline definitions reviewed and versioned with code.
Atlassian’s YAML Specs example was tested on Bamboo 9.6.1 and is supplied as-is. The article warns that a shared Specs repository may scan all plans and deployments there; a single commit can trigger many plans, use agents, and delay builds. For its include example, Atlassian recommends keeping plan definitions and permissions in separate files. Validate Specs structure and behavior in a non-production environment on your target version. [Read the YAML Specs guidance and caveats](https://support.atlassian.com/bamboo/kb/how-to-use-bamboo-yaml-specs-to-manage-multiple-plans-and-deployments-in-one-repository/).
| Choice | Consider it when | Check before adopting |
|---|---|---|
| Bamboo UI | You want to configure and inspect a plan directly in Bamboo. | How the team reviews, copies, and keeps plan changes consistent. |
| YAML Specs | You want configuration as code and reusable definitions. | Target-version support, repository scan scope, permissions, and the effect of a Specs commit on other plans. |
7. Verify the pipeline before production
- Run a build from a representative commit and confirm Bamboo checked out the intended repository revision.
- Confirm the agent uses the expected PHP and Composer versions and has required extensions.
- Introduce or select a known failing check and confirm the plan fails visibly.
- Inspect the build output and verify the downstream artifact contains the intended files.
- Run a deployment to a non-production environment and verify the deployed revision.
- Exercise the release gate and trigger behavior your team plans to use.
These are operational checks for your project, not claims of independent testing. Record the versions, commands, and artifact paths that worked so agent changes and Bamboo upgrades can be reviewed against them.
Common Bamboo PHP pipeline problems
| Symptom | Likely cause | What to check or change |
|---|---|---|
php or composer is not found |
The agent service has a different PATH from your shell, or the tool is not installed on that agent. |
Check the agent account’s environment and executable path. Install/provision the tool on eligible agents and configure the relevant capability where applicable. |
| Dependency installation fails | PHP version, extensions, Composer constraints, network access, or private package credentials do not match the project. | Compare the agent runtime with composer.json and composer.lock; verify required extensions and provide package credentials through an approved secret mechanism. |
| Tests pass locally but fail on Bamboo | Different runtime or environment, missing services, permissions, timezone, or configuration. | Compare runtime versions and environment variables; provision required services and use explicit test configuration. Avoid relying on a developer’s local state. |
| A failing command does not fail the plan | The script masks its exit code or a later command succeeds. | Use shell failure handling such as set -euo pipefail where appropriate, and inspect the Bamboo task’s exit-code handling. |
| Deployment cannot find a file | The build did not publish it, the artifact path is wrong, or the deployment plan retrieves a different artifact. | Inspect the build artifact contents and align the configured paths between build and deployment plans. |
| A Specs commit starts too many scans or builds | The repository contains multiple plans/deployments that the Specs scan processes. | Review repository organization, includes, and trigger effects in a safe environment before adopting the shared-repository layout. |
| Deployment starts before a person is ready | The trigger is automatic or the assumed approval behavior is not configured. | Review deployment triggers and implement the documented manual-stage workaround if it fits; verify it on the installed release. |
Performance, reliability, and cost considerations
Build time
Dependency installation, test suites, and external services usually determine how long a PHP build takes. Measure the actual stages in Bamboo before optimizing. Reuse dependency caches only when your team can keep them correct across relevant PHP versions, lock-file changes, and agent environments; stale or cross-project caches can make builds unreliable.
Reliability
- Pin or deliberately manage runtime and dependency versions so agent changes are visible.
- Fail the build when required checks fail, and keep logs useful without exposing secrets.
- Make external dependencies explicit and provide the required services consistently.
- Keep deployment credentials in the team’s approved secret store or Bamboo configuration rather than the repository or build artifact.
- Validate Specs changes and deployment behavior before applying them broadly.
Cost and agent capacity
Pipeline cost depends on your Bamboo licensing and infrastructure arrangements, agent capacity, and how much work builds and deployments run. The cited sources do not provide a PHP-specific cost or performance benchmark. A shared Specs commit that scans or triggers many plans can occupy agents and delay other builds, so account for its operational impact.
Or skip the browser setup
If a PHP pipeline also needs website screenshots for a visual check or release artifact, the pipeline can call ScreenshotNeo’s screenshot API instead of installing and maintaining browser capture setup on an agent. [ScreenshotNeo](https://screenshotneo.com) returns a PNG, JPEG, WebP, or PDF from a GET request. See the [API documentation](https://screenshotneo.com/docs/) for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Each feature is on every plan.
Sign up for 1,000 free screenshots a month, with no card.
FAQ
Does Bamboo install PHP when I add a PHPUnit capability?
No. A Bamboo agent capability identifies an executable available to the agent; prepare and verify the PHP runtime and related tools separately.
Are the sample Composer commands guaranteed to fit every PHP project?
No. The example assumes a Composer project with a lock file and a test script. Adapt it to the scripts, constraints, and services your repository defines.
Does Bamboo have a native deployment approval workflow in the cited guidance?
The cited Atlassian article describes a manual-stage workaround for approval-like gating. Check the documentation for your installed release and confirm the behavior you need.
Can I use Bamboo Specs for the pipeline?
YAML Specs are an option for configuration as code. Validate the structure and repository-scan effects for your Bamboo version before applying it to production plans.
