env-ci
Get environment variables exposed by CI services.
Note
Adds Subversion support to the env-ci module created by Pierre Vanduynslager. Adapted from codecov-node and the original env-ci.
Install
$ npm install --save env-ci
Usage
const envCi = require('env-ci');
const {name, service, isCi, branch, commit, tag, build, buildUrl, job, jobUrl, isPr, pr, prBranch, slug, root} = envCi();
if (isCI) {
console.log(`Building repo ${slug} on ${name} service`);
if (isPr) {
console.log(`Building Pull Request #${pr} originating from branch ${prBranch} and targeting branch ${branch}`);
} else {
console.log(`Building branch ${branch}`);
}
if (service === 'travis') {
// Do something specific to Travis CI
}
}
Supported variables
Variable | Description |
---|---|
name |
CI service Commercial name (e.g. Travis CI , CircleCI , GitLab CI/CD ) |
service |
Standardized CI service name (e.g. travis , circleci , gitlab ) |
isCi |
true is running on a CI, false otherwise |
branch |
Git branch being built or targeted by a Pull Request |
commit |
Commit sha that triggered the CI build |
tag |
Git tag that triggered the CI build |
build |
CI service build number |
buildUrl |
Link to the CI service build |
job |
CI service job number |
jobUrl |
Link to the CI service job |
isPr |
true if the build has been triggered by a Pull Request, false otherwise |
pr |
Pull Request number (only for builds triggered by a Pull Request) |
prBranch |
Git branch branch from which the Pull Request originated (only for builds triggered by a Pull Request) |
slug |
The slug (in form: owner_name/repo_name) of the repository currently being built |
root |
The path to the directory where the repository is being built |
Note: Some variables can be detected only on certain CI services. See Supported CI.
Note: The pr
and prBranch
properties are only available for builds triggered when a Pull Request is opened/updated and not on builds triggered by a push on a branch even if that branch happens to be the branch from which the Pull Request originated.
Supported CI
CI Service (name ) |
service |
isCi |
branch |
commit |
tag |
build |
buildUrl |
job |
jobUrl |
isPr |
pr |
prBranch |
slug |
root |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AppVeyor | appveyor |
|||||||||||||
Bamboo | bamboo |
|||||||||||||
Bitbucket | bitbucket |
|||||||||||||
Bitrise | bitrise |
|||||||||||||
Buddy | buddy |
|||||||||||||
Buildkite | buildkite |
|||||||||||||
CircleCI | circleci |
|||||||||||||
Cirrus CI | cirrus |
|||||||||||||
AWS CodeBuild | codebuild |
|||||||||||||
Codefresh | codefresh |
|||||||||||||
Codeship | codeship |
|||||||||||||
Drone | drone |
|||||||||||||
GitHub Actions | github |
|||||||||||||
GitLab CI/CD | gitlab |
|||||||||||||
Jenkins | jenkins |
|||||||||||||
Puppet | puppet |
|||||||||||||
Sail CI | sail |
|||||||||||||
Scrutinizer | scrutinizer |
|||||||||||||
Semaphore | semaphore |
|||||||||||||
Shippable | shippable |
|||||||||||||
TeamCity | teamcity |
|||||||||||||
Travis CI | travis |
|||||||||||||
Visual Studio Team Services | vsts |
|||||||||||||
Wercker | wercker |
Note: Unsupported properties will always be undefined
. For example if a Ci services doesn't support triggering builds when a Pull Request is opened/updated, isPr
will be undefined
.
Note: If none of the above CI services is detected, commit
and branch
are determined based on the local Git repository, and isCi
is determined based on the CI
environment variable.
API
envCi(options) => Result
options
Type: Object
env
Type: Object
Default: process.env
The object to read environment variables from.
cwd
Type: String
Default: process.cwd()
The current working directory in which to execute git
commands used to determine the commit
and branch
Result properties in case no supported CI is detected.
Result
Type: Object
Environment variables values exposed by the CI service.
Caveats
AWS CodeBuild
AWS CodeBuild doesn't provide an environment variable to determine the current Git branch being built. In addition, it clones the repository in a detached head state so the branch cannot be determined with git rev-parse --abbrev-ref HEAD
.
To work around this limitation, env-ci
look for the remote branches having the same HEAD
as the local detached HEAD
to determine the branch from which the detached HEAD
was created.
In the rare case where there is multiple remote branches with the same HEAD
as the local detached HEAD
, env-ci
will arbitrarily pick the first one. This can lead to an inaccurate branch
value in such circumstances.
Buddy
For builds triggered when a Pull Request is opened/updated, Buddy doesn't provide an environment variable indicating the branch from which the Pull Request originated nor the target branch. It also build from a branch named pull/<PR number>
so the target branch cannot be determined with a git
command.
Therefore in the case of Pull Request builds, env-ci
will not be able to determine the branch
and prBranch
properties.
See feature request.
CircleCI
For builds triggered when a Pull Request is opened/updated, CircleCI doesn't provide an environment variable indicating the target branch.
Therefore in the case of Pull Request builds, env-ci
will not be able to determine the branch
property. However prBranch
will be set.
See feature request.
Jenkins
Triggering build when a Pull Request is opened/updated is supported only via the ghprb-plugin and gitlab-plugin. Therefore env-ci
will set isPr
, pr
and prBranch
and define branch
with the Pull Request target branch only if one those plugin is used.
Sail
For builds triggered when a Pull Request is opened/updated, Sail doesn't provide an environment variable indicating the target branch, and the one for the current branch is set to pull/<PR number>
independently of the the branch name from which the Pull Request originated.
Therefore in the case of Pull Request builds, env-ci
will not be able to determine the branch
and prBranch
properties.
Semaphore
For builds triggered when a Pull Request is opened/updated, Semaphore 1.0 doesn't provide an environment variable indicating the target branch.
Therefore in the case of Pull Request builds, env-ci
will not be able to determine the branch
property. However prBranch
will be set.
On Semaphore 2.0 the branch
and prBranch
properties will work as expected.
The property tag
is only available on Semaphore 2.0.