GitLab CI Env

GitLab CI Env returns an object containing all of the predefined environment variables provided by GitLab CI.

Usage

1const gitlabEnv = require('gitlab-ci-env');
2
3const projectName = gitlabEnv.ci.project.name;
4const commitSha = gitlabEnv.ci.commit.sha;

Variable reference

The GitLab predefined environment variables are grouped by function. Generally this hierarchy can be derived from the name, for example CI_COMMIT_REF_NAME and CI_COMMIT_REF_SLUG are provided via ci.commit.ref.name and ci.commit.ref.slug respectively. There are some exceptions, which are included as properties in the most appropriate functional location.

A complete mapping of the GitLab predefined environment variables to the object provided by this module is given below for reference (values equal variable names).

1{
2  chat: {
3    channel: 'CHAT_CHANNEL',
4    input: 'CHAT_INPUT',
5    userID: 'CHAT_USER_ID'
6  },
7  ci: {
8    apiGraphqlUrl: 'CI_API_GRAPHQL_URL',
9    apiV4Url: 'CI_API_V4_URL',
10    buildsDir: 'CI_BUILDS_DIR',
11    commit: {
12      author: 'CI_COMMIT_AUTHOR',
13      beforeSha: 'CI_COMMIT_BEFORE_SHA',
14      branch: 'CI_COMMIT_BRANCH',
15      description: 'CI_COMMIT_DESCRIPTION',
16      message: 'CI_COMMIT_MESSAGE',
17      ref: {
18        name: 'CI_COMMIT_REF_NAME',
19        slug: 'CI_COMMIT_REF_SLUG',
20      },
21      refProtected: 'CI_COMMIT_REF_PROTECTED',
22      sha: 'CI_COMMIT_SHA',
23      shortSha: 'CI_COMMIT_SHORT_SHA',
24      tag: 'CI_COMMIT_TAG',
25      tagMessage: 'CI_COMMIT_TAG_MESSAGE',
26      timestamp: 'CI_COMMIT_TIMESTAMP',
27      title: 'CI_COMMIT_TITLE',
28    },
29    concurrentID: 'CI_CONCURRENT_ID',
30    concurrentProjectID: 'CI_CONCURRENT_PROJECT_ID',
31    configPath: 'CI_CONFIG_PATH',
32    debug: {
33        services: 'CI_DEBUG_SERVICES',
34        trace: 'CI_DEBUG_TRACE'
35    },
36    defaultBranch: 'CI_DEFAULT_BRANCH',
37    defaultBranchSlug: 'CI_DEFAULT_BRANCH_SLUG',
38    dependencyProxy: {
39        directGroupImagePrefix: 'CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX',
40        groupImagePrefix: 'CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX',
41        password: 'CI_DEPENDENCY_PROXY_PASSWORD',
42        server: 'CI_DEPENDENCY_PROXY_SERVER',
43        user: 'CI_DEPENDENCY_PROXY_USER'
44    },
45    deploy: {
46      freeze: 'CI_DEPLOY_FREEZE',
47      password: 'CI_DEPLOY_PASSWORD',
48      user: 'CI_DEPLOY_USER',
49    },
50    environment: {
51      action: 'CI_ENVIRONMENT_ACTION',
52      isDisposable: 'CI_DISPOSABLE_ENVIRONMENT',
53      name: 'CI_ENVIRONMENT_NAME',
54      slug: 'CI_ENVIRONMENT_SLUG',
55      tier: 'CI_ENVIRONMENT_TIER',
56      url: 'CI_ENVIRONMENT_URL',
57    },
58    externalPullRequest: {
59      iid: 'CI_EXTERNAL_PULL_REQUEST_IID',
60      source: {
61        branch: {
62          name: 'CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME',
63          sha: 'CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA'
64        },
65        repository: 'CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY'
66      },
67      target: {
68        branch: {
69          name: 'CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME',
70          sha: 'CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA'
71        },
72        repository: 'CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY'
73      }
74    },
75    hasOpenRequirements: 'CI_HAS_OPEN_REQUIREMENTS',
76    isCI: 'CI',
77    job: {
78      groupName: 'CI_JOB_GROUP_NAME',
79      id: 'CI_JOB_ID',
80      image: 'CI_JOB_IMAGE',
81      manual: 'CI_JOB_MANUAL',
82      name: 'CI_JOB_NAME',
83      nameSlug: 'CI_JOB_NAME_SLUG',
84      stage: 'CI_JOB_STAGE',
85      startedAt: 'CI_JOB_STARTED_AT',
86      status: 'CI_JOB_STATUS',
87      timeout: 'CI_JOB_TIMEOUT',
88      token: 'CI_JOB_TOKEN',
89      url: 'CI_JOB_URL',
90    },
91    kubeConfig: 'KUBECONFIG',
92    kubernetesActive: 'CI_KUBERNETES_ACTIVE',
93    mergeRequest: {
94      approved: 'CI_MERGE_REQUEST_APPROVED',
95      assignees: 'CI_MERGE_REQUEST_ASSIGNEES',
96      description: 'CI_MERGE_REQUEST_DESCRIPTION',
97      descriptionTruncated: 'CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED',
98      diff: {
99          baseSha: 'CI_MERGE_REQUEST_DIFF_BASE_SHA',
100          id: 'CI_MERGE_REQUEST_DIFF_ID'
101      },
102      draft: 'CI_MERGE_REQUEST_DRAFT',
103      eventType: 'CI_MERGE_REQUEST_EVENT_TYPE',
104      id: 'CI_MERGE_REQUEST_ID',
105      iid: 'CI_MERGE_REQUEST_IID',
106      labels: 'CI_MERGE_REQUEST_LABELS',
107      milestones: 'CI_MERGE_REQUEST_MILESTONE',
108      project: {
109        id: 'CI_MERGE_REQUEST_PROJECT_ID',
110        path: 'CI_MERGE_REQUEST_PROJECT_PATH',
111        url: 'CI_MERGE_REQUEST_PROJECT_URL',
112      },
113      refPath: 'CI_MERGE_REQUEST_REF_PATH',
114      source: {
115        branch: {
116          name: 'CI_MERGE_REQUEST_SOURCE_BRANCH_NAME',
117          protected: 'CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED',
118          sha: 'CI_MERGE_REQUEST_SOURCE_BRANCH_SHA',
119        },
120        project: {
121          id: 'CI_MERGE_REQUEST_SOURCE_PROJECT_ID'
122          path: 'CI_MERGE_REQUEST_SOURCE_PROJECT_PATH',
123          url: 'CI_MERGE_REQUEST_SOURCE_PROJECT_URL'
124        },
125      },
126      squashOnMerge: 'CI_MERGE_REQUEST_SQUASH_ON_MERGE',
127      target: {
128        branch: {
129          name: 'CI_MERGE_REQUEST_TARGET_BRANCH_NAME',
130          protected: 'CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED',
131          sha: 'CI_MERGE_REQUEST_TARGET_BRANCH_SHA'
132        },
133      },
134      title: 'CI_MERGE_REQUEST_TITLE',
135    },
136    node: {
137      index: 'CI_NODE_INDEX',
138      total: 'CI_NODE_TOTAL',
139    },
140    pages: {
141      domain: 'CI_PAGES_DOMAIN',
142      hostname: 'CI_PAGES_HOSTNAME',
143      url: 'CI_PAGES_URL',
144    },
145    pipeline: {
146      createdAt: 'CI_PIPELINE_CREATED_AT',
147      id: 'CI_PIPELINE_ID',
148      iid: 'CI_PIPELINE_IID',
149      name: 'CI_PIPELINE_NAME',
150      schedule: {
151          description: 'CI_PIPELINE_SCHEDULE_DESCRIPTION'
152      },
153      source: 'CI_PIPELINE_SOURCE',
154      triggered: 'CI_PIPELINE_TRIGGERED',
155      url: 'CI_PIPELINE_URL',
156    },
157    project: {
158      classificationLabel: 'CI_PROJECT_CLASSIFICATION_LABEL',
159      description: 'CI_PROJECT_DESCRIPTION',
160      dir: 'CI_PROJECT_DIR',
161      id: 'CI_PROJECT_ID',
162      name: 'CI_PROJECT_NAME',
163      namespace: {
164          fullPath: 'CI_PROJECT_NAMESPACE',
165          id: 'CI_PROJECT_NAMESPACE_ID',
166          slug: 'CI_PROJECT_NAMESPACE_SLUG'
167      },
168      openMergeRequests: 'CI_OPEN_MERGE_REQUESTS',
169      path: 'CI_PROJECT_PATH',
170      pathSlug: 'CI_PROJECT_PATH_SLUG',
171      repositoryLanguages: 'CI_PROJECT_REPOSITORY_LANGUAGES',
172      rootNamespace: 'CI_PROJECT_ROOT_NAMESPACE',
173      title: 'CI_PROJECT_TITLE',
174      url: 'CI_PROJECT_URL',
175      visibility: 'CI_PROJECT_VISIBILITY',
176    },
177    registry: {
178      image: 'CI_REGISTRY_IMAGE',
179      password: 'CI_REGISTRY_PASSWORD',
180      registry: 'CI_REGISTRY',
181      url: 'CI_REPOSITORY_URL',
182      user: 'CI_REGISTRY_USER',
183    },
184    release: {
185        description: 'CI_RELEASE_DESCRIPTION'
186    },
187    runner: {
188      description: 'CI_RUNNER_DESCRIPTION',
189      executableArch: 'CI_RUNNER_EXECUTABLE_ARCH',
190      id: 'CI_RUNNER_ID',
191      revision: 'CI_RUNNER_REVISION',
192      shortToken: 'CI_RUNNER_SHORT_TOKEN',
193      tags: 'CI_RUNNER_TAGS',
194      version: 'CI_RUNNER_VERSION',
195    },
196    server: {
197      fqdn: 'CI_SERVER_FQDN',
198      host: 'CI_SERVER_HOST',
199      isServer: 'CI_SERVER',
200      name: 'CI_SERVER_NAME',
201      port: 'CI_SERVER_PORT',
202      protocol: 'CI_SERVER_PROTOCOL',
203      revision: 'CI_SERVER_REVISION',
204      ssh: {
205        host: `CI_SERVER_SHELL_SSH_HOST`,
206        port: `CI_SERVER_SHELL_SSH_PORT`
207      },
208      tlsCaFile: 'CI_SERVER_TLS_CA_FILE',
209      tlsCertFile: 'CI_SERVER_TLS_CERT_FILE',
210      tlsKeyFile: 'CI_SERVER_TLS_KEY_FILE',
211      url: 'CI_SERVER_URL',
212      version: {
213        major: 'CI_SERVER_VERSION_MAJOR',
214        minor: 'CI_SERVER_VERSION_MINOR',
215        patch: 'CI_SERVER_VERSION_PATCH',
216        version: 'CI_SERVER_VERSION',
217      },
218    },
219    sharedEnvironment: 'CI_SHARED_ENVIRONMENT',
220    templateRegistryHost: `CI_TEMPLATE_REGISTRY_HOST`,
221    trigger: {
222        payload: `TRIGGER_PAYLOAD`,
223        shortToken: `CI_TRIGGER_SHORT_TOKEN`
224    }
225  },
226  gitlab: {
227    features: 'GITLAB_FEATURES',
228    fipsMode: 'CI_GITLAB_FIPS_MODE',
229    isCI: 'GITLAB_CI',
230    user: {
231      email: 'GITLAB_USER_EMAIL',
232      id: 'GITLAB_USER_ID',
233      login: 'GITLAB_USER_LOGIN',
234      name: 'GITLAB_USER_NAME',
235    },
236  },
237}

A complete listing of the GitLab predefined environment variables with descriptions can be found at https://docs.gitlab.com/ee/ci/variables/predefined_variables.html.