A GitHub Action to streamline installation of PHP dependencies with Composer.
ramsey/composer-install is a GitHub Action to streamline installation of Composer dependencies in workflows. It installs your Composer dependencies and caches them for improved build times.
This project adheres to a code of conduct. By participating in this project and its community, you are expected to uphold this code.
This GitHub Action requires PHP and Composer. One way to ensure you have both is to use the Setup PHP GitHub Action.
The step that sets up PHP and Composer for your environment must come before the ramsey/composer-install step.
Use ramsey/composer-install as step within a job. This example also shows use of the Setup PHP action as a step.
- uses: "shivammathur/setup-php@v2"
with:
php-version: "latest"
- uses: "ramsey/composer-install@v3"💡 There is no need to set up a separate caching step since ramsey/composer-install handles this for you.
The dependency-versions input parameter allows you to select whether the job
should install the locked, highest, or lowest versions of Composer dependencies.
Valid values are:
-
locked: (default) installs the locked versions of Composer dependencies (equivalent to runningcomposer install) -
highest: installs the highest versions of Composer dependencies (equivalent to runningcomposer update) -
lowest: installs the lowest versions of Composer dependencies (equivalent to runningcomposer update --prefer-lowest --prefer-stable)
For example:
- uses: "ramsey/composer-install@v3"
with:
dependency-versions: "lowest"ramsey/composer-install always passes the --no-interaction, --no-progress,
and --ansi options to the composer command. If you'd like to pass additional
options, you may use the composer-options input parameter.
For example:
- uses: "ramsey/composer-install@v3"
with:
composer-options: "--ignore-platform-reqs --optimize-autoloader"The working-directory input parameter allows you to specify a different
location for your composer.json file. For example, if your composer.json is
located in packages/acme-foo/, use working-directory to tell
ramsey/composer-install where to run things.
- uses: "ramsey/composer-install@v3"
with:
working-directory: "packages/acme-foo"You may use this step as many times as needed, if you have multiple
composer.json files.
For example:
# Install dependencies using composer.json in the root.
- uses: "ramsey/composer-install@v3"
# Install dependencies using composer.json in src/Component/Config/
- uses: "ramsey/composer-install@v3"
with:
working-directory: "src/Component/Config"
# Install dependencies using composer.json in src/Component/Validator/
- uses: "ramsey/composer-install@v3"
with:
working-directory: "src/Component/Validator"If you have jobs for which you wish to completely ignore the caching step, you
may use the ignore-cache input parameter. When present, ramsey/composer-install
will neither read from nor write to the cache.
Values of 'yes', true, or 1 will tell the action to ignore the cache. For
any other value, the action will use the default behavior, which is to read from
and store to the cache.
- uses: "ramsey/composer-install@v3"
with:
ignore-cache: "yes"There may be times you wish to specify your own cache key. You may do so with
the custom-cache-key input parameter. When provided, ramsey/composer-install
will not use the auto-generated cache key, so if your composer.json or
composer.lock files change, you'll need to update the custom cache key if you
wish to update the cache.
- uses: "ramsey/composer-install@v3"
with:
custom-cache-key: "my-custom-cache-key"ramsey/composer-install will auto-generate a cache key which is composed of
the following elements:
- The OS image name, like
ubuntu-latest. - The exact PHP version, like
8.1.11. - The options passed via
composer-options. - The dependency version setting as per
dependency-versions. - The working directory as per
working-directory. - A hash of the
composer.jsonand/orcomposer.lockfiles.
If you don't want to generate your own cache key, but do want to make the cache key
even more specific, you can specify a suffix to be added to the cache key via the
custom-cache-suffix parameter.
# Adds a suffix to the cache key which is equivalent to the full date-time
# of "last Monday 00:00", which means that the cache will be force refreshed
# via the first workflow which is run every Monday.
- uses: "ramsey/composer-install@v3"
with:
custom-cache-suffix: $(/bin/date -u --date='last Mon' "+%F")custom-cache-key will take precedence over the custom-cache-suffix.
Sometimes it's needed to use the repositories key in your composer.json to pull in forks, PRs with patches or private repositories. In this case, your GitHub Action may start failing with a Could not authenticate against github.com error message. To solve this, you need to add a GitHub Personal Access token, and this bit to your Action configuration:
env:
COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.COMPOSER_AUTH }}"}}'In this example, COMPOSER_AUTH is the name of the secret that you'll need to create. To access public repositories, the public_repo scope is sufficient, while for private repositories (that you can access), read:project will be needed.
For more information on how to do that on your repository, see Creating a personal access token and Creating encrypted secrets for a repository on GitHub documentation.
GitHub Workflows allow you to set up a job matrix, which allows you to configure multiple jobs for the same steps by using variable substitution in the job definition.
Here's an example of how you might use the dependency-versions and
composer-options input parameters as part of a job matrix.
strategy:
matrix:
php:
- "7.4"
- "8.0"
- "8.1"
- "8.2"
dependencies:
- "lowest"
- "highest"
include:
- php-version: "8.3"
composer-options: "--ignore-platform-reqs"
steps:
- uses: "actions/checkout@v4"
- uses: "shivammathur/setup-php@v2"
with:
php-version: "${{ matrix.php }}"
- uses: "ramsey/composer-install@v3"
with:
dependency-versions: "${{ matrix.dependencies }}"
composer-options: "${{ matrix.composer-options }}"Contributions are welcome! Before contributing to this project, familiarize yourself with CONTRIBUTING.md.
The ramsey/composer-install GitHub Action is copyright © Ben Ramsey and licensed for use under the terms of the MIT License (MIT). Please see LICENSE for more information.