Deploy a Git repository via SSH using GitLab's CI/CD Pipeline

This document provides step-by-step instructions to configure and use a GitLab CI/CD pipeline for deploying a Git repository via SSH.

1. Create GitLab CI/CD Variables

In your GitLab project:

Go to Settings → CI/CD → Variables.

Add the following variables with the specified options:

Variable Name	Description	Options
`BRANCH_NAME`	The branch to deploy (e.g., `main` or `master`)	Visible, Protected, Expand variable reference
`SSH_USER`	The SSH username for the target server	Visible, Protected, Expand variable reference
`SSH_HOST`	The target server's hostname or IP	Visible, Protected, Expand variable reference
`WORK_DIR`	The working directory on the remote server where code should be deployed	Visible, Protected, Expand variable reference

Create two sensitive variables:

Variable Name	Description	Options
`SSHPASS`	SSH password (used by `sshpass`)	Masked, Hidden, Protected, Expand variable reference
`SSH_PRIVATE_KEY`	Base64-encoded SSH private key	Masked, Hidden, Protected, Expand variable reference

Note:

You must base64-encode your private SSH key before adding it to GitLab. Use the following command to do this:

base64 -w 0 file_name_of_rsa_priv_key

Copy the resulting encoded string and set it as the value of SSH_PRIVATE_KEY in your GitLab variables.

2. Create a GitLab Access Token

Go to Settings → Access Tokens in your repository.
Create a new token with:
- Role: Reporter
- Scopes: read_api, read_repository
Copy and save the generated token securely.

3. Clone the Repository on the Web Server

To deploy your code to a server, clone your repository using the Access Token.

Use the following command syntax:

git clone "https://YourRepoName:YourAccessToken@git.example.org/group/YourRepoName.git" targetDirectoryName

Example:

If your repository is github.com/moodle/moodle, and you want to clone it into a folder named moodle45:

git clone "https://moodle:YourAccessToken@github.com/moodle/moodle.git" moodle45

Hint: YourRepoName is the repository name without the group name (e.g., moodle or DB).

4. Configure the GitLab CI/CD Pipeline

Open your project's .gitlab-ci.yml file in CI/CD → Editor and use the following configuration:

cache:
  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"

variables:
  TRAVIS_BUILD_DIR: '$CI_PROJECT_DIR'
  DOCKER_HOST: tcp://localhost:2375
  DOCKER_TLS_CERTDIR: ''

stages:
  - deploy

deploy:
  stage: deploy
  image: debian:stable
  tags:
    - shared_docker

  only:
    - main

  before_script:
    - apt-get -yq clean
    - apt-get -yq update
    - apt-get -yqq install ssh git sshpass
    - install -m 600 -D /dev/null ~/.ssh/id_rsa
    - echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/id_rsa
    - ssh-keyscan -H $SSH_HOST > ~/.ssh/known_hosts

  script:
    # The server supports only password authentication, so sshpass is used for non-interactive login.
    - sshpass -e ssh -o StrictHostKeyChecking=no $SSH_USER@$SSH_HOST "cd $WORK_DIR && git checkout $BRANCH_NAME && git pull && exit"

  after_script:
    - rm -rf ~/.ssh

5. Pipeline Execution Explanation

Section	Purpose
cache	Caches intermediate build data based on the job stage and commit reference.
variables	Sets required environment variables for Docker and the build directory.
stages	Defines the `deploy` stage as the only stage in this pipeline.
deploy job	Uses a Debian image to run deployment commands. It's restricted to run only on the `main` branch.
before_script	Installs necessary tools (`ssh`, `git`, `sshpass`), prepares SSH keys, and adds the host to known hosts.
script	Executes the SSH deployment — logs into the target server and performs `git checkout` and `git pull` on the defined branch and directory.
after_script	Cleans up sensitive SSH files after the job completes.

6. Workflow Summary

Push code changes to the main branch.
GitLab triggers the pipeline.
The runner prepares a Debian environment.
SSH credentials and environment variables are configured.
The pipeline connects to your target server using sshpass.
The repository on the server is updated using git pull.
Cleanup happens after deployment.

7. Troubleshooting Tips

SSH Authentication Fails:
Verify that SSH_USER, SSH_HOST, and SSHPASS are correct.
Also, confirm that your private key matches the server's public key.
Permission Denied Errors:
Ensure the GitLab runner has permission to access protected variables.
Pipeline Doesn't Trigger:
Confirm that your branch name matches the one specified in only: (e.g., main).

8. Security Recommendations

Always mask and protect sensitive variables (SSHPASS, SSH_PRIVATE_KEY).
Avoid using personal tokens; use project access tokens.
Periodically rotate your SSH keys and tokens for security.
Do not log sensitive values in job logs.

Author: C.