GitLab Shell feature list

Discover

Allows users to identify themselves on an instance with SSH. The command helps to confirm quickly whether a user has SSH access to the instance:

ssh git@<hostname>

PTY allocation request failed on channel 0
Welcome to GitLab, @username!
Connection to staging.gitlab.com closed.

When permission is denied, it returns:

ssh git@<hostname>
git@<hostname>: Permission denied (publickey).

Git operations

GitLab Shell provides support for Git operations over SSH by processing git-upload-pack, git-receive-pack and git-upload-archive SSH commands. It limits the set of commands to predefined Git commands:

git archive
git clone
git pull
git push

Git operation timeout (`gitlab_shell_git_timeout`)

The gitlab_shell_git_timeout setting controls the timeout, in seconds, for Git import and fetch operations executed by GitLab Shell. This includes repository synchronization performed by Geo secondary nodes.

Default value

The default timeout is 10800 seconds (3 hours).

When to adjust this setting

You may need to increase this value when:

Synchronizing large repositories, especially in Geo deployments
Operating over slow or constrained network connections
Git operations fail with timeout-related errors after several hours

If the timeout is too low, Git operations may terminate before completion, even though data transfer is still progressing.

Generate new 2FA recovery codes

Enables users to generate new 2FA recovery codes:

$ ssh git@<hostname> 2fa_recovery_codes

Are you sure you want to generate new two-factor recovery codes?
Any existing recovery codes you saved will be invalidated. (yes/no)
yes

Your two-factor authentication recovery codes are:
...

Verify 2FA OTP

Allows users to verify their 2FA one-time password (OTP):

$ ssh git@<hostname> 2fa_verify

OTP: 347419

OTP validation failed.

LFS authentication

Enables users to generate credentials for LFS authentication:

$ ssh git@<hostname> git-lfs-authenticate <project-path> <upload/download>

{"header":{"Authorization":"Basic ..."},"href":"https://gitlab.com/user/project.git/info/lfs","expires_in":7200}

Personal access token

Enables users to use personal access tokens with SSH:

$ ssh git@<hostname> personal_access_token <name> <scope1[,scope2,...]> [ttl_days]

Token:   glpat-...
Scopes:  api
Expires: 2022-02-05

Configuration options

Administrators can control PAT generation with SSH. To configure PAT settings in GitLab Shell:

Edit the /etc/gitlab/gitlab.rb file.
Add or modify the following configuration:
```
gitlab_shell['pat'] = { enabled: true, allowed_scopes: [] }
```
- enabled: Set to true to enable PAT generation using SSH, or false to disable it.
- allowed_scopes: An array of scopes allowed for PATs generated with SSH. Leave empty ([]) to allow all scopes.
Save the file and Restart GitLab.

Edit the values.yaml file:
```
gitlab:
  gitlab-shell:
    config:
      pat:
        enabled: true
        allowedScopes: []
```
- enabled: Set to true to enable PAT generation using SSH, or false to disable it.
- allowedScopes: An array of scopes allowed for PATs generated with SSH. Leave empty ([]) to allow all

Save the file and apply the new values:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Edit the docker-compose.yaml file:
```
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_shell['pat'] = { enabled: true, allowed_scopes: [] }
```
- enabled: Set to 'true' to enable PAT generation using SSH, or 'false' to disable it.
- allowed_scopes: A comma-separated list of scopes allowed for PATs generated with SSH. Leave empty ([]) to allow all scopes.
Save the file and restart GitLab and its services:
```
docker compose up -d
```

Edit the /home/git/gitlab-shell/config.yml file:
```
pat:
  enabled: true
  allowed_scopes: []
```
- enabled: Set to true to enable PAT generation using SSH, or false to disable it.
- allowed_scopes: An array of scopes allowed for PATs generated with SSH. Leave empty ([]) to allow all scopes.

Save the file and restart GitLab Shell:

# For systems running systemd
sudo systemctl restart gitlab-shell.target

# For systems running SysV init
sudo service gitlab-shell restart

These settings only affect PAT generation with SSH and do not impact PATs created through the web interface.