Secrets

This document lists all secrets, tokens and credentials that can be configured and managed by a non-administrator user in GitLab.

For each item, a concise explanation of its usage and a link to the official documentation are provided.

Quick Selection Guide

Choose the appropriate credential type based on your needs:

Tokens

Personal Access Tokens (PATs)

Personal access tokens serve as authentication credentials that function as password substitutes.

Personal access tokens are based on a specific user’s permissions and provide the same level of access as that user account.

Use Personal Access Tokens when:

• You need to access GitLab API with your own user permissions
• You want to clone/push repositories via HTTPS instead of SSH
• You’re developing scripts or tools that interact with GitLab on your behalf

Check the official Personal Access Tokens page for more information.

Configuration

To generate a token:

• User menu > Edit profile > Access tokens

Project Access Tokens

Project access tokens are similar to passwords, except you can limit access to resources, select a limited role, and provide an expiry date.

Use Project Access Tokens when:

• You need automated access limited to a single project (e.g., external integrations, bots)
• You want to isolate credentials for a specific project rather than using personal credentials
• You need API access for project-specific automation (issue tracking, CI/CD triggers)
• You need to grant external tools access to one project without exposing other projects

Check the official Project Access Tokens page for more information.

Configuration

To create a project access token:

• Navigate to your project > Settings > Access tokens

Group Access Tokens

Group access tokens enable users to perform actions for groups and manage the projects within the group.

Use Group Access Tokens when:

• You need access to multiple projects within a group from a single credential
• You’re setting up organization-wide integrations (monitoring, security scanning, reporting tools)
• You want to automate operations across all projects in a group

Check the GitLab Group Access Tokens page for more information.

Configuration

To create a group access token:

• Navigate to your group > Settings > Access tokens

Deploy Tokens

Specialized credentials designed for automated deployments and CI/CD pipelines.

They provide read-only or read-write access to a project’s (or group’s) container registry and package repositories without requiring user authentication. Deploy tokens are scoped, have configurable expiration dates, and cannot be used to access the GitLab UI or API—only specific package management and container registry operations.

Use Deploy Tokens when:

• You need automated, read-only access to container images or packages (e.g., in CI/CD pipelines, production servers, or deployment automation)
• You want to pull artifacts without exposing user credentials or granting full API access

Check the Deploy Tokens page for more information.

Configuration

Navigate to Settings > Repository > Deploy tokens at either Project level or Group level.

CI/CD Job Tokens

CI/CD job tokens are unique credentials automatically generated by GitLab when a pipeline job runs. These tokens are made available to the job as the CI_JOB_TOKEN predefined variable.

Job tokens remain valid exclusively during job execution and are revoked immediately after completion. The token inherits the access level of the user who initiated the pipeline.

Use CI/CD Job Tokens when:

• Your pipeline jobs need to pull/push Docker images to the container registry
• You need to download or publish packages within pipeline jobs
• Your jobs need to access GitLab API endpoints (branches, commits, merge requests)
• You want to clone other repositories within a pipeline job

Check the CI/CD Job Tokens page for more information.

Keys

Keys provide SSH-based authentication to GitLab repositories. Unlike tokens that use HTTPS, keys leverage SSH protocol with asymmetric cryptography (public/private key pairs). Keys are ideal for secure communication and can be used both for personal development and automated system access.

SSH Keys

SSH keys enable secure communication between users and GitLab servers using SSH protocol. Rather than entering credentials repeatedly, GitLab uses cryptographic key pairs for authentication.

SSH keys employ asymmetric cryptography with a public key (safe to distribute) and a private key (must remain protected). The private key can additionally sign commits for enhanced security.

Use SSH Keys when you want to interact with GitLab repositories from your development machine via SSH.

See the GitLab SSH Keys page for more information.

Configuration

1. Generate keys using ssh-keygen with appropriate algorithms
2. Add public keys to their GitLab account profile (User menu > Edit profile > SSH Keys)
3. Set optional expiration dates for enhanced security

Deploy Keys

Deploy keys facilitate non-human interaction with GitLab repositories using SSH protocol. They are primarily used to access repositories from external systems like build or CI servers.

Deploy keys are SSH key pairs where the public key is added to GitLab.

See the GitLab Deploy Keys page for more information.

Configuration

• Maintainers can create keys via Settings > Repository > Deploy Keys
• Add the public SSH key with optional write permissions and expiration dates

CI/CD Variables

CI/CD variables are the primary mechanism for storing credentials and sensitive configuration values in GitLab pipelines. They enable secure storage of credentials for external services (API keys, passwords, tokens), certificates, and any sensitive configuration that should not be exposed in pipeline logs or hardcoded in .gitlab-ci.yml files.

Variables are made available as environment variables in CI/CD jobs.

Configuration

Variables can be defined at three levels:

• Project Level: Settings > CI/CD > Variables (maximum 8,000 variables)
• Group Level: Make variables available across all projects in a group (maximum 30,000 variables)
• Instance Level: Available to all projects and groups (GitLab Self-Managed/Dedicated only)