Composer Authentication

Publish PHP packages to Packagist

How Packagist Works

Unlike npm or PyPI, you don't push packages to Packagist. Instead:

1. Register your package on Packagist (one-time setup)
2. Configure a GitHub webhook to notify Packagist of updates
3. When you push a tag, Packagist fetches the new version from your repo
4. Users can immediately composer require your package

Initial Setup

1. Register on Packagist

1. Go to packagist.org and sign in
2. Click "Submit" and enter your repository URL
3. Packagist will validate your composer.json

2. Configure GitHub Webhook

This ensures Packagist updates immediately when you push tags:

1. Go to your repo Settings → Webhooks
2. Add webhook with URL: https://packagist.org/api/github?username=YOUR_PACKAGIST_USERNAME
3. Content type: application/json
4. Secret: Get from your Packagist profile → "Show API Token"
5. Events: Select "Just the push event"

Workflow Configuration

Release Pilot just needs to create and push tags:

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: a-line-services/release-pilot@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Release Pilot Configuration

In your .github/release-pilot.yml:

ecosystem: composer
versionFile: composer.json
tagPrefix: v

composer.json Requirements

{
  "name": "vendor/package-name",
  "description": "A short description of your package",
  "type": "library",
  "license": "MIT",
  "autoload": {
    "psr-4": {
      "Vendor\\\\PackageName\\\\": "src/"
    }
  },
  "require": {
    "php": ">=8.1"
  }
}

Note: Packagist extracts versions from Git tags, not from composer.json. You don't need a version field.

Private Packages

For private packages, you have several options:

Private Packagist

Private Packagist is the commercial offering for private packages:

1. Sign up at packagist.com
2. Add your private repository
3. Configure authentication in your projects

Satis (Self-Hosted)

Run your own Composer repository with Satis:

# satis.json
{
  "name": "My Private Repository",
  "homepage": "https://packages.example.com",
  "repositories": [
    {"type": "vcs", "url": "git@github.com:your-org/private-package.git"}
  ],
  "require-all": true
}

VCS Repository (Direct)

For small teams, reference private repos directly in composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:your-org/private-package.git"
    }
  ],
  "require": {
    "your-org/private-package": "^1.0"
  }
}

Version Constraints

Composer uses semantic versioning with these tag formats:

Verifying Your Release

After Release Pilot creates a tag:

1. Check your package page on Packagist for the new version
2. The webhook should trigger within seconds
3. If not updating, manually click "Update" on your Packagist package page

# Test installation
composer require your-vendor/your-package:1.2.3

Troubleshooting