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
- Status:
Online tests, executed directly in every supported CI enviromnent
- AppVeyor:
- GitHub Actions:
- TravisCI:
  - Push tests:
  - Pull request tests:

mlocati / ci-info

Maintainers

Details