CI Detector

PHP library to detect continuous integration environment and to read information of the current build.

Why

This library is useful if you need to detect whether some CLI script/tool is running in an automated environment (on a CI server).
Based on that, your script may behave differently. For example, it could hide some information which relevant only for
a real person - like a progress bar.

Additionally, you may want to detect some information about the current build: build ID, git commit, branch etc.
For example, if you’d like to record these values to log, publish them to Slack, etc.

How

The detection is based on environment variables injected to the build environment by each CI server.
However, these variables are named differently in each CI. This library contains adapters for many supported
CI servers to handle these differences, so you can make your scripts (and especially CLI tools) portable to multiple
build environments.

Supported continuous integration servers

These CI servers are currently recognized:

• AppVeyor
• AWS CodeBuild
• Azure DevOps Pipelines
• Bamboo
• Bitbucket Pipelines
• Buddy
• CircleCI
• Codeship
• continuousphp
• drone
• GitHub Actions
• GitLab
• Jenkins
• SourceHut
• TeamCity
• Travis CI
• Wercker

If your favorite CI server is missing, feel free to send a pull-request!

Installation

Install using Composer:

$ composer require ondram/ci-detector

Example usage

<?php

$ciDetector = new \OndraM\CiDetector\CiDetector();

if ($ciDetector->isCiDetected()) { // Make sure we are on CI environment
    echo 'You are running this script on CI server!';
    $ci = $ciDetector->detect(); // Returns class implementing CiInterface or throws CiNotDetectedException

    // Example output when run inside GitHub Actions build:
    echo $ci->getCiName(); // "GitHub Actions"
    echo $ci->getBuildNumber(); // "33"
    echo $ci->getBranch(); // "feature/foo-bar" or empty string if not detected

    // Conditional code for pull request:
    if ($ci->isPullRequest()->yes()) {
        echo 'This is pull request. The target branch is: ';
        echo $ci->getTargetBranch(); // "main"
    }

    // Conditional code for specific CI server:
    if ($ci->getCiName() === OndraM\CiDetector\CiDetector::CI_GITHUB_ACTIONS) {
        echo 'This is being built on GitHub Actions';
    }

    // Describe all detected values in human-readable form:
    print_r($ci->describe());
    // Array
    // (
    //     [ci-name] => GitHub Actions
    //     [build-number] => 33
    //     [build-url] => https://github.com/OndraM/ci-detector/commit/abcd/checks
    //     [commit] => fad3f7bdbf3515d1e9285b8aa80feeff74507bde
    //     [branch] => feature/foo-bar
    //     [target-branch] => main
    //     [repository-name] => OndraM/ci-detector
    //     [repository-url] => https://github.com/OndraM/ci-detector
    //     [is-pull-request] => Yes
    // )

} else {
    echo 'This script is not run on CI server';
}

API methods reference

Available methods of CiInterface instance (returned from $ciDetector->detect()):

Method	Example value	Description
getCiName()	GitHub Actions	Name of the CI server. The value is one of CiDetector::CI_* constants.
getBuildNumber()	33	Get number of this concrete build. Build number is usually human-readable increasing number sequence. It should increase each time this particular job was run on the CI server. Most CIs use simple numbering sequence like: 1, 2, 3… However, some CIs do not provide this simple human-readable value and rather use for example alphanumeric hash.
getBuildUrl()	https://github.com/OndraM/ci-detector/commit/abcd/checks or empty string	Get URL where this build can be found and viewed or empty string if it cannot be determined.
getCommit()	b9173d94(...)	Get hash of the git (or other VCS) commit being built.
getBranch()	my-feature or empty string	Get name of the git (or other VCS) branch which is being built or empty string if it cannot be determined. Use getTargetBranch() to get name of the branch where this branch is targeted.
getTargetBranch()	main or empty string	Get name of the target branch of a pull request or empty string if it cannot be determined. This is the base branch to which the pull request is targeted.
getRepositoryName()	OndraM/ci-detector or empty string	Get name of the git (or other VCS) repository which is being built or empty string if it cannot be determined. This is usually in form “user/repository”, for example OndraM/ci-detector.
getRepositoryUrl()	https://github.com/OndraM/ci-detector or empty string	Get URL where the repository which is being built can be found or empty string if it cannot be determined. This is either HTTP URL like https://github.com/OndraM/ci-detector but may be a git ssh url like ssh://[email protected]/OndraM/ci-detector
isPullRequest()	TrinaryLogic instance	Detect whether current build is from a pull/merge request. Returned TrinaryLogic object’s value will be true if the current build is from a pull/merge request, false if it not, and maybe if we can’t determine it (see below for what CI supports PR detection). Use condition like if ($ci->isPullRequest()->yes()) { /*...*/ } to use the value.
describe()	[...] (array of values)	Return key-value map of all detected properties in human-readable form.

Supported properties of each CI server

Most CI servers support (✔) detection of all information. However some don’t expose
necessary environment variables, thus reading some information may be unsupported (❌).

CI server	Constant of CiDetector	is​PullRequest	get​Branch	get​Target​Branch	get​Repository​Name	get​Repository​Url	get​Build​Url
AppVeyor	CI_APPVEYOR	✔	✔	✔	✔	❌	✔
AWS CodeBuild	CI_AWS_CODEBUILD	✔	✔	❌	❌	✔	✔
Azure Pipelines	CI_AZURE_PIPELINES	✔	✔	✔	✔	✔	✔
Bamboo	CI_BAMBOO	✔	✔	✔	✔	✔	✔
Bitbucket Pipelines	CI_BITBUCKET_PIPELINES	✔	✔	✔	✔	✔	✔
Buddy	CI_BUDDY	✔	✔	✔	✔	✔	✔
CircleCI	CI_CIRCLE	✔	✔	❌	✔	✔	✔
Codeship	CI_CODESHIP	✔	✔	❌	✔	❌	✔
continuousphp	CI_CONTINUOUSPHP	✔	✔	❌	❌	✔	✔
drone	CI_DRONE	✔	✔	✔	✔	✔	✔
GitHub Actions	CI_GITHUB_ACTIONS	✔	✔	✔	✔	✔	✔
GitLab	CI_GITLAB	✔	✔	✔	✔	✔	✔
Jenkins	CI_JENKINS	❌	✔	❌	❌	✔	✔
SourceHut	CI_SOURCEHUT	✔	❌	❌	❌	❌	✔
TeamCity	CI_TEAMCITY	❌	❌	❌	❌	❌	❌
Travis CI	CI_TRAVIS	✔	✔	✔	✔	❌	✔
Wercker	CI_WERCKER	❌	✔	❌	✔	❌	✔

Testing

Check codestyle, static analysis and run unit-tests:

composer all

To automatically fix codestyle violations run:

composer fix

Standalone CLI version

If you want to use CI Detector as a standalone CLI command (ie. without using inside code of PHP project),
see ci-detector-standalone repository, where you can
download CI Detector as a standalone PHAR file with simple command line interface.

Changelog

For latest changes see CHANGELOG.md file. This project follows Semantic Versioning.

Similar libraries for other languages

Similar “CI Info” libraries exists for some other languages, for example:

• Go - KlotzAndrew/ci-info
• JavaScript/Node.js - watson/ci-info
• Python - mgxd/ci-info
• Rust - sagiegurari/ci_info