GitLab Plugin
GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager including a wiki, issue-tracking, and continuous integration and deployment pipeline features.
The Akeyless plugin for GitLab enables a secure, easy, and integrative way to fetch Secrets into GitLab pipelines.
Authentication
Each job has a JSON Web Token (JWT) provided as CI/CD variable named CI_JOB_JWT_V2
.
When a pipeline is about to run, GitLab uses the CI_JOB_JWT_V2
job token and generates a unique token for it.
The CI_JOB_JWT_V2
is an RS256
JSON web token that is being used to authenticate with third-party systems that support JWT authentication, in our case, Akeyless.
The token is valid only while the pipeline job runs. After the job finishes, you canβt use the token anymore.
To work with the Akeyless GitLab plugin, we will use an OAuth 2.0 / JWT Authentication Method
OAuth 2.0 / JWT
In Akeyless Platform, create a new OAuth 2.0 / JWT Authentication Method with the following parameters:
akeyless create-auth-method-oauth2 --name \Dev\GitLabAuth \
--jwks-uri https://gitlab.com/-/jwks \
--unique-identifier user_login
--force-sub-claims
Where:
-
--jwks-uri
- The URL to theJWKS
that contains the public keys that should be used for JWT verification. -
--unique-identifier
- A unique claim name that contains details uniquely identifying the request. In the following example, we will use the GitLabuser_login
claim. -
--force-sub-claims
- Enforce Sub-Claims on role association.
Create a dedicated Access Role, please note that you will assign it the necessary permissions in a later stage of this guide:
akeyless create-role --name \Dev\GitLabRole \
Associate your new Role with the created Authentication Method, and assign it Sub Claims:
akeyless assoc-role-am --role-name \Dev\GitLabRole \
--am-name \Dev\GitLabAuth \
--sub-claims user_login=<YOUR GitLab USERNAME>
Sub Claims:
It is mandatory to add an appropriate Sub Claim based on the claims available in the GitLab documentation to prevent access of unauthorized users.
Set Read
and List
permissions for Secrets & Keys:
akeyless set-role-rule --role-name \Dev\GitLabRole \
--path /Path/To/your/secret/'*' \
--capability read --capability list
Usage
Open your GitLab project and make sure you have a yaml
file named .gitlab-ci.yml
and update it to contain the following steps while making sure that the path to the relevant secrets, as well as the access-id value with your matching JWT access-id, was replaced.
If you are working with your own Akeyless Gateway, set the value of the VAULT_ADDR
field as your Akeyless Gateway URL on port 8200. For example, https://akeyless-gw:8200
.
GitLab Version 15 and higher
Starting from v15 GitLab supports
CI_JOB_JWT_V2
, for older versions you can use the legacy environmentCI_JOB_JWT
instead.The image is
akeyless/ci_base
which is a public docker image based onruby:2.4
that contains the Akeyless CLI as well as other essential components.
variables:
ACCESS_ID: <access_id>
akeyless:
image:
name: akeyless/ci_base:latest-alpine
before_script:
- export MY_SECRET=akeyless://path/to/secret # Static / Dynamic secret
- export VAULT_ADDR=https://hvp.akeyless.io
- export TOKEN=$(akeyless auth --access-id $ACCESS_ID --access-type jwt --jwt $CI_JOB_JWT_V2)
- source ~/.akeyless/akeyless_env.sh
script:
- echo "Fetching Secrets is Easy [$MY_SECRET]"
Sample output of a successful job:

Success! - the secrets are accessible to use within the job logic (in this example, they are just being printed).
Updated 2 months ago