Host private Composer packages in Buddy

Buddy now has a Composer artifact type and a Composer Publish action. A pipeline can publish a PHP package to a private Composer repository in your workspace, and applications can install it with a regular composer install. Both features were introduced in the November 10 release.

Until now, a private package often meant a paid service such as Private Packagist or a vcs repository in composer.json with an SSH key or a Git token in every pipeline. The registry in Buddy separates installing packages from access to the source repository. The app only needs a token with permission to read artifacts.

In this example we publish laravel-health with a /health endpoint and install it in a Laravel app.

How the Composer registry works

Composer sees the artifact as a regular composer repository at https://composer.registry.sh. The package name is <workspace domain>/<artifact identifier>, so in the acme workspace the laravel-health artifact accepts the acme/laravel-health package. The required vendor applies only to the package name. You don't have to change PHP namespaces.

Versions can't be overwritten. Publishing 1.0.0 again fails with Artifact 'version' must be unique.

Image loading...laravel-health artifact, Versions tab with published package versions

Publish a package from a pipeline

The first action copies only what belongs in the package to dist/. The second one publishes that directory and creates the artifact on the first run:

yaml
- action: Prepare package
  type: BUILD
  docker_image_name: library/composer
  docker_image_tag: "2"
  commands: |-
    composer validate --no-check-publish
    rm -rf dist && mkdir dist
    cp -r composer.json src dist/
- action: Publish to Composer registry
  type: COMPOSER_PUBLISH
  artifact: laravel-health
  path: dist

Image loading...Composer Publish action: laravel-health artifact, dist directory, optional version and description

The version comes from composer.json or from the Version field in the action and must use a valid semantic version without a v prefix. If the version comes from a Git tag, remove the prefix because v1.1.0 fails validation. Publish from a separate directory because the action includes all files in the configured path, including .git.

Install a private package with composer install

In the app, add the registry and the dependency:

json
"require": {
    "laravel/framework": "^12.0",
    "acme/laravel-health": "^1.0"
},
"repositories": [
    { "type": "composer", "url": "https://composer.registry.sh" }
]

Then run composer update acme/laravel-health locally and commit the updated composer.lock. Subsequent composer install runs will install the package version recorded in the lockfile.

The registry requires a personal access token with the ARTIFACT_READ scope. In the pipeline, store it as an encrypted COMPOSER_TOKEN variable and pass it through COMPOSER_AUTH to avoid writing the credentials to auth.json.

yaml
- action: Install Composer dependencies
  type: BUILD
  docker_image_name: library/php
  docker_image_tag: 8.5-cli
  setup_commands: |-
    apt-get update && apt-get install -y git unzip
    curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
  commands: |-
    mkdir -p storage/framework/views storage/framework/cache storage/framework/sessions storage/logs bootstrap/cache
    export COMPOSER_AUTH="{\"http-basic\":{\"composer.registry.sh\":{\"username\":\"token\",\"password\":\"$COMPOSER_TOKEN\"}}}"
    composer install --no-dev --no-interaction --prefer-dist

The token is masked in the action logs:

Image loading...Install Composer dependencies action log: the token in COMPOSER_AUTH is masked

The app doesn't have to be built in Buddy. You can install the package from the registry locally or in another CI system with the same token. A ready-to-use composer.json snippet and the command for setting up the token locally are in the artifact under Pull artifact.

Image loading...Pull artifact window: composer.json snippet and token setup command

Control who can publish and install

In the artifact's Permissions tab, you can configure access for workspace members, pipelines, and sandboxes. An artifact created by Composer Publish initially allows publishing only from the pipeline that created it. Other pipelines receive Pipeline is not allowed to publish artifact until permission is granted in this tab or with the Grant permissions button in the failed run.

Image loading...laravel-health artifact Permissions tab: Deny for all pipelines, Read-write for publish-package

Test a new package version automatically

Version 1.1.0 adds an environment field to the response. Update the dependency with composer update acme/laravel-health, commit the updated composer.lock, and run the application's pipeline. After deployment, /health returns:

json
{
  "status": "ok",
  "app": "Acme Dashboard",
  "environment": "production",
  "php": "8.5.12",
  "laravel": "12.72.0",
  "checks": {
    "storage_writable": true
  },
  "health_package": "1.1.0"
}

Publishing a version also emits the Publish artifact version event. You can use it to trigger a separate application pipeline that runs composer update acme/laravel-health, starts the application, and checks /health. If the application fails to start or the endpoint returns an HTTP error, the run fails. The example below omits the setup already shown in the install action, including setup_commands, the storage directories, and COMPOSER_AUTH:

yaml
- pipeline: test-health-package
  refs:
  - refs/heads/main
  events:
  - type: PUBLISH_ARTIFACT_VERSION
    artifacts:
    - laravel-health:*
  actions:
  - action: Update laravel-health and test
    type: BUILD
    docker_image_name: library/php
    docker_image_tag: 8.5-cli
    commands: |-
      composer update acme/laravel-health --no-dev --no-interaction --prefer-dist
      cp .env.example .env && php artisan key:generate --force
      php artisan serve --port=8000 > /dev/null 2>&1 &
      curl -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8000/health

The pipeline requires the Use role in the artifact's Permissions tab. Without it, the run cannot access the artifact.

What's next

Add the Composer Publish action to your package's pipeline and point your apps at composer.registry.sh. Configuration details are in the docs:

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