Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

SSH Keys and Access Tokens

Connect Git to GitLab securely: generate SSH keys, add them to your profile, compare personal, project and deploy tokens, and choose the right scopes.

Your browser logs in with a password and two-factor code. Git and scripts cannot do that, so GitLab offers other ways to prove who you are: SSH keys for Git over SSH, and tokens for Git over HTTPS and for the API. Choosing the right credential and giving it the smallest possible power is one of the most important habits you can build.

SSH keys

An SSH key is a pair of files. The private key stays on your computer and must never be shared. The public key is safe to share and goes into GitLab. When you connect, GitLab checks that you hold the matching private key without ever seeing it.

Generate a modern Ed25519 key:

Terminal
ssh-keygen -t ed25519 -C "[email protected]"

Accept the default file location (~/.ssh/id_ed25519) and set a passphrase. This creates two files: id_ed25519 (private) and id_ed25519.pub (public). Then:

  1. Print the public key: cat ~/.ssh/id_ed25519.pub (on Windows PowerShell use Get-Content).
  2. In GitLab open your avatar, then Preferences or Edit profile, then SSH Keys, and choose Add new key.
  3. Paste the whole line, which starts with ssh-ed25519, give it a title such as "Work laptop", and optionally set an expiry date.
  4. Test the connection:
Terminal
ssh -T [email protected]

A successful test prints a welcome message that includes your username. The first time, SSH asks you to confirm the server's fingerprint; compare it with the fingerprints published in GitLab's documentation before typing yes.

If you use several accounts or hosts, describe each in ~/.ssh/config:

TEXT
Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519

What a fingerprint is

GitLab and ssh-keygen -l identify keys by a fingerprint: the SHA-256 hash of the decoded key data, encoded in base64 without padding and prefixed with SHA256:. The stand-in below computes it for a made-up public key, using the same algorithm. (The key bytes here are fake; a real key line has real cryptographic material.)

Python Stand-in: compute an SSH key fingerprint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Because the fingerprint depends only on the key, GitLab can show it next to each key you add, and you can compare it to the output of ssh-keygen -lf ~/.ssh/id_ed25519.pub to be sure the right key was uploaded.

Tokens: for HTTPS and the API

If you clone with an HTTPS URL, Git asks for a username and password. GitLab does not accept your account password there when two-factor authentication is on. Instead, use a personal access token as the password. Tokens are also how scripts call the GitLab REST API.

Create one under your profile in Access tokens: give it a name, an expiry date, and select scopes. Copy the token immediately; GitLab shows it only once. Common scopes:

Scope Allows
read_repository Clone and pull over HTTPS
write_repository Push over HTTPS
read_api Read-only API access
api Full API access (read and write)
read_registry / write_registry Pull or push container images
create_runner Create runners (for automation)

You can then call the API from a terminal:

Terminal
curl --header "PRIVATE-TOKEN: <your_token>" "https://gitlab.com/api/v4/projects?membership=true"

Never paste real tokens into code, chat or screenshots. Treat them like passwords.

Which credential for which job?

There are several kinds of token, each scoped to a different owner.

  • Personal access token: acts as you, with your permissions. Good for your own scripts. If you leave the company, it stops working with your account.
  • Project access token and group access token: act as a bot user tied to that project or group, with a role you choose (for example Reporter). Better for shared automation, because they survive people leaving.
  • Deploy token: read-only (or registry write) access to a project's repository, packages and registry, with no user attached. Ideal for servers that only need to pull.
  • Deploy key: an SSH key you add to a project, optionally read-only, so a server can clone without a user account.
  • CI job token (CI_JOB_TOKEN): created automatically for each pipeline job and valid only while it runs. It lets a job pull dependencies or call limited API endpoints without you storing a secret.
  • Trigger and feed tokens exist for pipeline triggers and RSS/calendar feeds.

The stand-in below turns this into a checker. Given the scopes on a token, it tells you which operations the token can perform. The scope table is a simplification of the real rules but follows the ideas above.

Python Stand-in: does this token have enough scope?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see that full-power can do almost everything, and that is exactly why you should prefer narrow tokens such as read_repository.

Security habits

  • Give tokens an expiry date (GitLab sets limits by default) and rotate them before they expire.
  • Use the fewest scopes that work, and prefer project or group tokens for automation.
  • Protect your private key with a passphrase and let an SSH agent remember it for your session.
  • If a token or key leaks, revoke it at once in the same settings page, then check the audit trail for activity.
  • Store secrets for pipelines in CI/CD variables marked masked and protected, never in .gitlab-ci.yml (see variables and rules).
  • Add secret scanning to your pipeline in the security chapter so a committed token is caught early.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file do you upload to GitLab?

    Only the public key is shared. The private key never leaves your machine.
  2. 2. You clone over HTTPS and your account has two-factor authentication. What should you use as the password?

    With 2FA enabled, HTTPS Git operations need a token (or another supported credential) instead of the password.
  3. 3. A production server must only pull code from one project. What is the best credential?

    Deploy tokens and read-only deploy keys give narrow, user-independent access.
  4. 4. What does CI_JOB_TOKEN give you?

    The job token is generated per job and expires when the job finishes.

Summary

  • SSH keys come in a private part you keep and a public part you add to your profile; test with ssh -T [email protected].
  • Over HTTPS, use a personal, project or group access token instead of a password.
  • Scopes such as read_repository, write_repository, read_api and api limit what a token can do; pick the smallest set.
  • Deploy tokens and deploy keys are for servers; the CI job token is for pipelines.
  • Set expiry dates, rotate credentials and revoke anything that leaks.

Next: Issues, Labels and Boards