mlocati / ci-info
Get informations about the current continuous integration environment
Installs: 100 198
Dependents: 2
Suggesters: 0
Security: 0
Stars: 3
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >=7.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.16
- phpunit/phpunit: ^8.5
This package is auto-updated.
Last update: 2024-10-29 14:29:41 UTC
README
This package lets you get details about the current Continuous Integration environment.
Supported environments are:
- AppVeyor
- GitHub Actions
- TravisCI
Installation
You can install this package in two ways:
- using composer:
composer require mlocati/ci-info
- manually: download a ZIP archive from the project Releases page.
Usage from within your PHP scripts
Setup
First of all, if you don't use Composer, you need to include the autoload.php
file you can find in the root directory of this project:
require_once 'path/to/autoload.php';
Usage
Determine the current CI Environment
$driver = (new \CIInfo\DriverList())->getDriverForEnvironment(); if ($driver === null) { // CI environment Not detected } else { if ($ci->getHandle() === \CIInfo\Driver\GithubActions::HANDLE) { // We are running in a GitHub Actions build } }
Get info about the current job
try { $state = (new \CIInfo\StateFactory())->getCurrentState(); } catch (\CIInfo\Exception $whoops) { echo "Something went wrong: " . (string) $whoops; return; } switch ($state->getEvent()) { case \CIInfo\State::EVENT_PUSH: // $state is an instance of the \CIInfo\State\Push (or its \CIInfo\State\PushWithoutBaseCommit subclass) class echo "We are in a build triggered by a push.\n"; break; case \CIInfo\State::EVENT_PULLREQUEST: // $state is an instance of the \CIInfo\State\PullRequest class echo "We are in a build triggered by a pull request.\n"; break; case \CIInfo\State::EVENT_TAG: // $state is an instance of the \CIInfo\State\Tag class echo "We are in a build triggered by the creation of a tag.\n"; break; case \CIInfo\State::EVENT_SCHEDULED: // $state is an instance of the \CIInfo\State\Scheduled class echo "We are in a build triggered by a scheduled job.\n"; break; case \CIInfo\State::EVENT_MANUAL: // $state is an instance of the \CIInfo\State\Manual class echo "We are in a build triggered manually (via APIs, manual builds, repository_dispatch events, ...).\n"; break; }
To see the methods available for every class, see the source code.
Usage from a shell
You can also use this library in your shell scripts (bash, sh, powershell, ...).
First of all, you have to determine the path of the ci-info
file. It's under the bin
directory (or composer/vendor/bin
for composer-based projects).
ci-info
can provide details about the current environment/job.
Here's a sample POSIX script:
$ driver="$(./bin/ci-info driver)" $ echo "The current CI environment is: $driver" The current CI environment is: travis-ci
Here's a sample PowerShell script:
PS> $driver="$(.\bin\ci-info driver)" PS> Write-Host "The current CI environment is: $driver" The current CI environment is: github-actions
To get the full list of the features of the ci-info
command, type:
$ ./bin/ci-info --help
Which outputs:
Syntax:
./bin/ci-info [-q|--quiet] [-h|--help] <command>
Options:
-q|--quiet: turn off displaying errors
-h|--help : show this syntax message and quits
Allowed values for <command> are:
# driver
Print the handle identifying the current environment.
Possible results are:
- appveyor: AppVeyor
- github-actions: GitHub Actions
- travis-ci: Travis CI
# event
Print the current operation type.
Possible results are:
- cron: Scheduled event
- manual: Manually triggered event (API calls, repository_dispatch events, forced rebuilds, ...)
- pr: Pull request event
- push: Push event
- tag: Tag creation event
# sha1
Print the SHA-1 of the most recent commit (it's the merge commit in case of pull requests)
# pr:base:branch
Print the target branch of a pull request
# pr:base:sha1
Print the SHA-1 of the last commit in the target branch
# pr:head:sha1
Print the SHA-1 of the last commit in the pull request branch
# pr:wrongsha1
Print the wrong SHA-1 of the merge commit of a pull request event as defined by the current environment.
For example, the TRAVIS_COMMIT environment variable defined in TravisCI may be wrong (see https://travis-ci.community/t/travis-commit-is-not-the-commit-initially-checked-out/3775 )
If there merge commit SHA-1 is correct, nothing gets printed out.
# pr:range
Print the commit range of pull request events (example: 123456abcded...abcded123456)
# push:branch
Print the name of the branch affected by a push event
# push:range:has
Check if the commit range is available.
In case it's not available, the exit code is 1, otherwise it's 0.
The reason why the range is not available is printed out to the standard error (use -q to prevent that).
# push:prev:sha1
Print the SHA-1 of the commit prior to the last commit for a push event
# push:range
Print the commit range of push events (example: 123456abcded...abcded123456)
# tag:name
Print the tag name (for tag jobs)
# manual:branch
Print the current branch in a manually-triggered job
# cron:branch
Print the current branch in a scheduled job
Exit code:
0: success
1: failure
Tests
This library is tested against two types of cases:
- Offline tests, implemented as GitHub Actions and managed by phpunit, which test the library against well-known environment statuses of the supported CI environment
- Online tests, executed directly in every supported CI enviromnent