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:

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
<?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
<?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
<?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...Workflow tab of the release-package pipeline: Git Push trigger on refs/tags/v* and the Run tests, Prepare package and Publish to Composer registry actions

yaml
- 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 in setup_commands because the official php image 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/, and vendor/ after composer install.
  • Publish to Composer registry publishes dist/ to the laravel-health artifact. 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).

Info
Tests check the repository, but you publish 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:

diff
-            '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:

bash
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...Run of the release-package pipeline for the v1.2.0 tag: Run tests failed, Prepare package and Publish to Composer registry skipped

The artifact still has only 1.0.0 and 1.1.0:

Image loading...Versions tab of the laravel-health artifact with versions 1.0.0 and 1.1.0, without 1.2.0

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...Run of the release-package pipeline for the v1.2.1 tag: Run tests, Prepare package and Publish to Composer registry finished successfully

The registry now lists 1.2.1 alongside 1.0.0 and 1.1.0:

Image loading...Versions tab of the laravel-health artifact with versions 1.0.0, 1.1.0 and 1.2.1

The version page displays the README.md copied to dist/. Without that file you only see the default composer require command there.

Image loading...Page of version 1.2.1 of the laravel-health artifact with the rendered README: installation, example response of the /health endpoint and requirements

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...Log of the Publish to Composer registry action in the second run for v1.2.1 with the error Artifact 'version' must be unique

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), while composer.json allows ^8.2. If you support older PHP, add a second test action with the tag of the lowest version.
  • Monorepo. path points to the directory with the package's composer.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.0 becomes 1.2.0 through ${BUDDY_RUN_TAG#v}, and composer.json has no version field to keep in sync.
  • Keep the failed tag, ship the fix under a new one. v1.2.0 stays in Git, nothing reached the registry, and the fix is version 1.2.1.

See also:

Jarek Dylewski

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.

Nov 16, 2026
Share