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.
- 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
{
"repositories": [
{ "type": "composer", "url": "https://acme.cacheport.cc/composer/" },
{ "packagist.org": false }
]
}Credentials
export COMPOSER_AUTH='{"http-basic":{"acme.cacheport.cc":{"username":"ci","password":"'"$CACHEPORT_TOKEN"'"}}}'
composer install --no-interactionDisabling 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
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/phpunitMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
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/phpunitMore 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.