Composer Delivery: Ship Private Packages Securely & Automatically

Private Composer Packages Delivery for Magento 2 — Secure, Automated Distribution

For Magento 2 B2B solutions, distributing proprietary extensions via Composer is standard practice. However, managing private packages introduces significant challenges in security, automation, and performance. A robust delivery pipeline is not a luxury; it is a core component of professional software distribution that directly impacts customer trust and operational efficiency. This guide outlines the architecture for a secure, automated system to deliver private Magento 2 packages.

1. Choosing Your Private Repository

The foundation of your distribution strategy is the Composer repository. This is not merely a file server; it manages package metadata, versions, and dependencies. The choice balances control, cost, and convenience.

Commercial Solutions: Private Packagist

Private Packagist offers a managed, feature-rich solution. It handles the complexities of metadata generation, provides a clean UI, and integrates with GitHub/GitLab/Bitbucket for automated package indexing. Its key value is offloading infrastructure management, offering fine-grained access control via teams and tokens, and providing commercial support. For teams without dedicated DevOps resources, this is often the most direct path to a professional setup.

Self-Hosted: Satis

Satis is a static Composer repository generator. You provide a `satis.json` configuration file listing your Git repositories, and Satis builds the necessary `packages.json` file and HTML assets. It is lightweight and offers full control. However, this control comes with responsibility. You must manage the hosting, secure the server, and automate the build process. A typical Satis workflow involves a webhook from your Git provider that triggers a script to run the `satis build` command, regenerating the repository metadata upon each new tag.

VCS & Artifact Registries

You can instruct Composer to pull directly from a Git repository using a `vcs` repository type. While simple for a single package, this approach scales poorly. Composer must clone each repository to resolve dependencies, leading to significant performance degradation. Artifact registries like GitLab's built-in Composer repository or JFrog Artifactory offer a more robust alternative. They centralize package management beyond PHP, but require specific configuration to work seamlessly as a Composer endpoint, often involving more complex CI/CD integration.

2. Robust Access Control and Entitlement

Securing your packages requires mapping a customer's purchase or license to repository access. The goal is to grant least-privilege, revocable access.

The Core: License-to-Token Mapping

Your backend system (e.g., Magento, CRM) must be the source of truth for entitlements. When a customer purchases an extension or subscription, your system should programmatically generate a unique set of Composer credentials. This typically involves creating a machine user or a scoped, read-only access token (e.g., a GitHub Personal Access Token or a GitLab Deploy Token). This token should be tied directly to the customer's license key or account ID in your database. This link is critical for automating access revocation.

Client-Side Authentication

Customers use these credentials by adding them to their `auth.json` file, located in the Composer home directory. This file is never committed to their project's version control. It instructs Composer how to authenticate with specific domains.

A typical customer-facing instruction would be to create or modify `~/.composer/auth.json` with the provided credentials:

3. The Automated CI/CD Publishing Pipeline

Manual package releases are slow and error-prone. A CI/CD pipeline ensures every release is consistent, tested, and secure. A Git tag push should trigger the entire workflow:

• Build: Run `composer install --no-dev` to ensure all production dependencies are met.
• Test: Execute automated tests (unit, integration, static analysis) to validate code quality and prevent regressions.
• Scan: Perform automated security scans on the codebase and its dependencies to identify known vulnerabilities.
• Sign: (Optional but recommended) GPG-sign the Git tag to verify its authenticity.
• Tag: The trigger itself is a SemVer-compliant Git tag (e.g., `1.2.3`).
• Publish: The pipeline archives the package and pushes it to the artifact registry or triggers the Satis rebuild.
• Notify: A final step sends a notification (e.g., via email or webhook) to customers and internal stakeholders.

4. Versioning and Release Channels

• SemVer: Follow semantic versioning. Reserve breaking changes for major releases, features for minor releases, and bug fixes for patches.
• Channels: Provide `stable`, `rc`, and `snapshot` channels. Use branch aliases or separate repositories to isolate pre-release packages.
• Constraints: Recommend safe Composer constraints (e.g., `^2.3`) that allow customers to receive fixes without absorbing breaking changes.

5. Security and Supply Chain Integrity

• Dependency Confusion: Prevent namespace collisions by using a private vendor prefix and prioritizing private repositories over packagist.org in the Composer configuration.
• Token Hygiene: Issue short-lived, scoped tokens. Rotate regularly and immediately revoke upon employee departure or license expiration.
• SBOM & Signatures: Generate a software bill of materials and optionally sign releases for tamper evidence.

6. Performance and Mirrors

• Metadata Caching: Put a CDN in front of your Satis or registry endpoint. Composer v2 relies heavily on fast metadata responses.
• Dist Mirrors: Serve tarballs/ZIPs from edge locations. Respect rate limits and throttle abusive clients.
• Composer Flags: Use `--prefer-dist`, `--no-dev`, and `--classmap-authoritative` for production installs.

7. Onboarding and Offboarding

• Automated Onboarding: Provide a portal that issues tokens, writes `auth.json`, and performs a smoke `composer install` to validate connectivity.
• Revocation: When a license expires or a contract ends, revoke the token and remove access immediately. Maintain a complete audit trail for compliance.

8. Observability and KPIs

• KPIs: Installation success rate, mean time to recovery (MTTR), time to release, and p95/p99 download latency.
• Tracing/Logging: Correlate installations with a unique ID. Classify errors (authentication, not found, rate limit) to identify systemic issues.

With a well-chosen repository, strict access controls, an automated pipeline, and clear KPIs, Composer delivery becomes a reliable, scalable pillar of your B2B distribution strategy.