Publish a private Composer package only after tests pass
A Git tag on a commit with a failing test should not become a version that apps can install.
This Buddy pipeline starts on every v* tag, runs PHPUnit, and publishes the private Composer package only when the tests pass. Installing the package, tokens, and registry basics are covered in Private Composer packages in Buddy.
The Composer package and its PHPUnit test
acme/laravel-health is a small Laravel package with a /health endpoint. The key parts of its composer.json:
{
"name": "acme/laravel-health",
"require": {
"php": "^8.2",
"illuminate/support": "^11.0|^12.0"
},
"require-dev": {
"phpunit/phpunit": "^11.0"
},
"autoload": {
"psr-4": { "Acme\\Health\\": "src/" }
},
"autoload-dev": {
"psr-4": { "Acme\\Health\\Tests\\": "tests/" }
}
}
There is no version field. The Git tag is the only source of the version, and the Composer documentation recommends omitting the field in that case.
The report status comes from the src/HealthReport.php class. Here it is trimmed to the fields that matter:
<?php
declare(strict_types=1);
namespace Acme\Health;
final class HealthReport
{
public static function make(bool $storageWritable): array
{
return [
'status' => $storageWritable ? 'ok' : 'degraded',
'checks' => [
'storage_writable' => $storageWritable,
],
];
}
}
HealthController builds the /health response with HealthReport::make(...) and returns 200 or 503. The test in tests/HealthReportTest.php checks that a healthy report returns the ok status:
<?php
declare(strict_types=1);
namespace Acme\Health\Tests;
use Acme\Health\HealthReport;
use PHPUnit\Framework\TestCase;
final class HealthReportTest extends TestCase
{
public function test_healthy_app_reports_ok(): void
{
$report = HealthReport::make(storageWritable: true);
$this->assertSame('ok', $report['status']);
}
}
To cover the provider, routing, and the /health response, add a separate test with Orchestra Testbench.
phpunit.xml in the package root loads vendor/autoload.php and runs the Package suite from the tests directory:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php" colors="true">
<testsuites>
<testsuite name="Package">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
Publishing the Composer package from a Git tag
The release-package pipeline starts whenever you push a tag that begins with v. Pushes to branches do not trigger it. The same trigger in the UI is described in Release after every tag push.
Image loading...
- pipeline: release-package
name: Release package
events:
- type: PUSH
refs:
- refs/tags/v*
actions:
- action: Run tests
type: BUILD
commands: |-
composer validate --no-check-publish
composer install --no-interaction
vendor/bin/phpunit
setup_commands: |-
apt-get update && apt-get install -y git zip unzip
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
docker_image_name: library/php
docker_image_tag: "8.5"
- action: Prepare package
type: BUILD
commands: |-
rm -rf dist && mkdir dist
cp -r composer.json README.md src dist/
export OUTPUT_PKG_VERSION="${BUDDY_RUN_TAG#v}"
docker_image_name: library/php
docker_image_tag: "8.5"
- action: Publish to Composer registry
type: COMPOSER_PUBLISH
path: dist
artifact: laravel-health
version: $OUTPUT_PKG_VERSION
- Run tests is a PHP action. It validates
composer.json, installs dependencies, and runs PHPUnit. Composer is installed insetup_commandsbecause the officialphpimage does not include it. When a test fails, the next actions do not run. - Prepare package, also a PHP action, copies only the package files to
dist/and turns the tag into a version. Publishing from the repository root would pack the whole directory, including.git,tests/, andvendor/aftercomposer install. - Publish to Composer registry publishes
dist/to thelaravel-healthartifact. It runs only when both previous actions succeed.
Run the same tests on pull requests. The release pipeline repeats them on the exact commit of the tag and is the last gate before publishing.
The tag and the version are two different values here. The default variable BUDDY_RUN_TAG contains the Git tag v1.2.0 without refs/tags/. ${BUDDY_RUN_TAG#v} removes the v. The OUTPUT_ prefix passes the result to the next action (see output variables), so Composer Publish receives 1.2.0.
Pass the tag with the v and Composer Publish fails with 'version' must be a valid semver (e.g., 1.0.0).
dist/.
Only composer.json, README.md, and src go to dist/. If the package also has config/, routes/, or resources/, add them to cp and add a check, for example test -d dist/config. When a directory is missing, the action fails and the package is not published.
A failing test blocks the release
The registry already has 1.0.0 and 1.1.0, published earlier by the pipeline from the blog post. Then the commit "Simplify status values" changes one string in HealthReport:
- 'status' => $storageWritable ? 'ok' : 'degraded',
+ 'status' => $storageWritable ? 'OK' : 'degraded',
It looks like cleanup. The commit gets the v1.2.0 tag, and pushing that single tag triggers the release pipeline:
git tag v1.2.0
git push origin v1.2.0
$$The test still expects ok, so the run ends at the tests and both following actions are skipped:
Image loading...
The artifact still has only 1.0.0 and 1.1.0:
Image loading...
In a registry that builds versions straight from repository tags, like Packagist or Satis, v1.2.0 would already be installable. Here no app can require 1.2.0, because that version was never published.
Release the fix as v1.2.1
The fix is Revert "Simplify status values". The v1.2.0 tag stays where it is. Deleting or moving it would rewrite tag history that others may have already fetched, so the fix gets the next version and the v1.2.1 tag.
In this demo 1.2.0 had only one change, so after the revert the code of 1.2.1 is the same as in 1.1.0. A real release usually includes other changes you still want to ship, and those go into 1.2.1.
The laravel-health artifact was created by the pipeline from the blog post, and only that pipeline can publish to it. Before release-package publishes its first version, add it in the artifact's Permissions tab with the Publish role. Otherwise Composer Publish returns the error Pipeline not allowed to Publish artifact.
This time PHPUnit reports OK (1 test, 1 assertion), BUDDY_RUN_TAG is v1.2.1, and the version passed to Composer Publish is 1.2.1:
Image loading...
The registry now lists 1.2.1 alongside 1.0.0 and 1.1.0:
Image loading...
The version page displays the README.md copied to dist/. Without that file you only see the default composer require command there.
Image loading...
Running the pipeline again for v1.2.1 fails at the publish step: Artifact 'version' must be unique. The pipeline does not overwrite a version that is already in the registry. The same number can be published again only after you manually delete the version from the artifact, so release changes under a new tag.
Image loading...
Publishing 1.2.1 does not change running apps. Each one gets the new version on its next deploy, after composer update acme/laravel-health and a commit of composer.lock.
If the app pipeline uploads vendor/ over SFTP, set filesystem_changeset_base: CONTENTS at the pipeline level there. Without it, the new modification timestamps after composer install force a re-upload of unchanged content.
Before you use it in your project
- PHP version. Tests run here on PHP 8.5 (
docker_image_tag), whilecomposer.jsonallows^8.2. If you support older PHP, add a second test action with the tag of the lowest version. - Monorepo.
pathpoints to the directory with the package'scomposer.json, so every package in the repository has its own directory and its own Composer Publish action. The action fields are described in Composer Publish YAML reference.
Takeaways
- A tag starts the release, but only a green run publishes. The pipeline starts on
v*, but Composer Publish runs only after the tests pass. - The tag and the version are two values. The Git tag
v1.2.0becomes1.2.0through${BUDDY_RUN_TAG#v}, andcomposer.jsonhas noversionfield to keep in sync. - Keep the failed tag, ship the fix under a new one.
v1.2.0stays in Git, nothing reached the registry, and the fix is version 1.2.1.
See also:
- Private Composer packages in Buddy - installing the package, tokens and the registry
- Private Composer dependencies in pipelines
bdy artifact composer publish- publishing from the terminal- Trigger on an artifact event - triggering an app pipeline whenever a new package version is published
Jarek Dylewski
Customer Support
A journalist and an SEO specialist trying to find himself in the unforgiving world of coders. Gamer, a non-fiction literature fan and obsessive carnivore. Jarek uses his talents to convert the programming lingo into a cohesive and approachable narration.