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

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.