Getting Started with GitLab CI/CD: Pipelines, Runners, and SSH Deployment

The purpose of this guide is to give a friendly, hands‑on introduction to GitLab CI/CD through a sample application, allowing newcomers to start using pipelines without reading the entire GitLab documentation.

Pipeline Basics

Continuous Integration works by pushing small code commits to a Git repository; each push triggers a scripted pipeline that builds, tests, and validates the changes before merging into the main branch. Continuous Delivery/Deployment extends this by automatically deploying to production after each successful push to the default branch.

GitLab CI/CD relies on a single .gitlab-ci.yml file placed at the repository root. The file defines jobs that are grouped into a pipeline . Jobs are organized into stages , and the order of execution follows the stages list.

Example Pipeline Configuration

stages:</code>
<code>  - build</code>
<code>  - test</code>
<code>  - deploy</code>
<code></code>
<code>image: alpine</code>
<code></code>
<code>build_a:</code>
<code>  stage: build</code>
<code>  script:</code>
<code>    - echo "This job builds something."</code>
<code></code>
<code>build_b:</code>
<code>  stage: build</code>
<code>  script:</code>
<code>    - echo "This job builds something else."</code>
<code></code>
<code>test_a:</code>
<code>  stage: test</code>
<code>  script:</code>
<code>    - echo "This job tests something. It will only run when all jobs in the"</code>
<code>    - echo "build stage are complete."</code>
<code></code>
<code>test_b:</code>
<code>  stage: test</code>
<code>  script:</code>
<code>    - echo "This job tests something else. It will only run when all jobs in the"</code>
<code>    - echo "build stage are complete too. It will start at about the same time as test_a."</code>
<code></code>
<code>deploy_a:</code>
<code>  stage: deploy</code>
<code>  script:</code>
<code>    - echo "This job deploys something. It will only run when all jobs in the"</code>
<code>    - echo "test stage complete."</code>
<code></code>
<code>deploy_b:</code>
<code>  stage: deploy</code>
<code>  script:</code>
<code>    - echo "This job deploys something else. It will only run when all jobs in the"</code>
<code>    - echo "test stage complete. It will start at about the same time as deploy_a."

The three stages—build, test, and deploy—contain the jobs shown in brackets: {build_a, build_b}, {test_a, test_b}, {deploy_a, deploy_b}. Jobs run in the order defined by the stages keyword.

You can use the only keyword to restrict jobs to specific branches, for example deploying to a staging server on one branch and to production on master:

deploy-production:</code>
<code>  stage: deploy</code>
<code>  script:</code>
<code>    - ./deploy_prod.sh</code>
<code>  only:</code>
<code>    - master

GitLab Runner

GitLab Runner is an open‑source agent that executes the jobs defined in the pipeline and reports results back to GitLab. It runs on Linux, macOS, FreeBSD, and Windows, and can be installed via Docker, binary download, or package managers.

When using Docker, ensure Docker is installed and run the runner container, for example:

docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register

During registration you provide the GitLab URL and a registration token, after which the runner writes its configuration to the mounted volume.

SSH‑Based Deployment

To deploy code from a CI/CD job to a private server, add an SSH key pair to the runner. Generate a key with: ssh-keygen -t rsa -b 4096 -C "example" Copy the public key to authorized_keys on the target server and store the private key in a GitLab CI/CD variable (e.g., SSH_PRIVATE_KEY). Then, in the pipeline, install the SSH client, add the key to the agent, and run the deployment command:

deploy_production:</code>
<code>  stage: deploy</code>
<code>  before_script:</code>
<code>    - apk add openssh-client</code>
<code>    - eval $(ssh-agent -s)</code>
<code>    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -</code>
<code>    - mkdir -p ~/.ssh</code>
<code>    - chmod 700 ~/.ssh</code>
<code>  script:</code>
<code>    - ssh -o StrictHostKeyChecking=no username@host_ip_address "cd /project && git pull"</code>
<code>  only:</code>
<code>    - master

Because the Alpine base image does not include an SSH client, the pipeline explicitly installs it. Adjust the commands if you use a different base image.

The article concludes with links to historical posts, author information, and promotional material for a DevOps pipeline course.