cacheport

Ecosystem · PHP

Packagist cache for Composer in CI

Composer downloads metadata from Packagist and archives from wherever each package is hosted, often GitHub. Cacheport caches both, so composer install stops depending on GitHub API limits and slow mirrors.

CP-COMPOSERManifest
Upstream
repo.packagist.org and package dist URLs
Endpoint
https://acme.cacheport.cc/composer/
Config
repositories in composer.json
Credentials
COMPOSER_AUTH (http-basic)
Metadata
Refreshed every 5 minutes
Dist archives
Cached forever per reference

How Composer caching works

Packagist publishes metadata; the zip files usually come from GitHub. Unauthenticated GitHub downloads are rate limited, which is a common cause of failing Composer installs on shared runners. Cacheport fetches each archive once and serves it to every later build.

The Cacheport repository advertises itself as a mirror for dist downloads, so Composer fetches archives through the cache even when composer.lock lists the original URLs.

What gets cached
Packagist metadata
p2 metadata files, refreshed every 5 minutes.
Dist archives
Cached per package reference, forever.
Source installs
--prefer-source clones from Git and bypasses the cache.

Set it up

composer.json

composer.json
{
  "repositories": [
    { "type": "composer", "url": "https://acme.cacheport.cc/composer/" },
    { "packagist.org": false }
  ]
}

Credentials

shell
export COMPOSER_AUTH='{"http-basic":{"acme.cacheport.cc":{"username":"ci","password":"'"$CACHEPORT_TOKEN"'"}}}'
composer install --no-interaction

Disabling the default packagist.org repository makes Composer resolve everything through Cacheport. COMPOSER_AUTH keeps credentials out of auth.json and the repository.

Use it in CI

Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.

GitHub Actions

.github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      COMPOSER_AUTH: '{"http-basic":{"acme.cacheport.cc":{"username":"ci","password":"${{ secrets.CACHEPORT_TOKEN }}"}}}'
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
      - run: composer install --no-interaction --prefer-dist
      - run: vendor/bin/phpunit

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
test:
  image: composer:2
  script:
    - export COMPOSER_AUTH="{\"http-basic\":{\"acme.cacheport.cc\":{\"username\":\"ci\",\"password\":\"$CACHEPORT_TOKEN\"}}}"
    - composer install --no-interaction --prefer-dist
    - vendor/bin/phpunit

More for GitLab CI: GitLab CI setup guide.

GitHub rate limits

Without a token, GitHub limits API and archive requests per IP address, and every runner behind a shared NAT counts against the same limit. With Cacheport, each archive is fetched from GitHub once for your whole workspace.

Troubleshooting

Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.

Questions

Does composer.lock need to change?

No. Composer uses the mirror information from the Cacheport repository to fetch the archives listed in the lockfile.

Do private packages work?

Yes. Add your private Composer repository or Private Packagist instance as an upstream.

What about --prefer-source?

Source installs clone Git repositories directly. Use --prefer-dist in CI to benefit from the cache.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.