GitLab CI: Server Deployment Script Guide

This guide explains how to set up GitLab CI/CD for deploying your application to a server using SSH.

Overview

The provided GitLab CI configuration creates a deployment pipeline that:

1. Runs only on the main branch
2. Uses Alpine Linux as the base image
3. Sets up SSH for secure server access
4. Executes a deployment script on the remote server

Prerequisites

• A GitLab repository
• A server with SSH access
• GitLab Runner with vm-runner tag
• SSH key pair for authentication

Configuration

1. GitLab CI Configuration File

Create .gitlab-ci.yml in your repository root:

stages:
  - deploy
 
deploy:
  image: alpine:latest
  tags:
    - vm-runner
  stage: deploy
  timeout: 5m
  only:
    - main
  before_script:
    - apk add --update --no-cache openssh-client curl net-tools sshpass
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY_NEW" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
    - echo "$SSH_PRIVATE_KEY_NEW" > ~/id_rsa
    - chmod 600 ~/id_rsa
  script:
    - ssh -i id_rsa -o StrictHostKeyChecking=no $SSH_USER@$SSH_HOST "cd /home/fyfirman/vtuber-cretivox && ./deploy.sh"
  when: manual

2. Environment Variables

Set the following environment variables in your GitLab project (Settings > CI/CD > Variables):

SSH_HOST=103.131.110.10
SSH_USER=fyfirman
SSH_PRIVATE_KEY_NEW=-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAv8dXxi8wNAOqBNOh8Dv5rh0BTb5KNgk3/SkJRDYYwgUmyV
...
YourActualPrivateKeyHere
...
-----END RSA PRIVATE KEY-----

⚠️ Important Security Notes:

• Never commit SSH keys or sensitive credentials directly in your repository
• Mark the SSH_PRIVATE_KEY_NEW variable as "Masked" and "Protected" in GitLab
• Use deploy keys or dedicated CI/CD SSH keys instead of personal SSH keys

3. SSH Key Setup

1. Generate a new SSH key pair:

   ssh-keygen -t rsa -b 4096 -C "gitlab-ci-deployment"

2. Add the public key to your server's ~/.ssh/authorized_keys:

   cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

3. Copy the private key content and paste it as the value for SSH_PRIVATE_KEY_NEW in GitLab CI/CD variables

How It Works

1. Stage Definition: The pipeline has a single deploy stage.

2. Runner Requirements: The job requires a runner with the vm-runner tag.

3. Execution Conditions:

   • Only runs on the main branch
   • Requires manual trigger (when: manual)
   • Times out after 5 minutes

4. Setup Phase (before_script):

   • Installs required SSH tools
   • Sets up SSH agent
   • Configures SSH keys and permissions
   • Adds the server to known hosts

5. Deployment Phase (script):

   • SSH's into the server
   • Changes to the project directory
   • Executes the deployment script

Troubleshooting

1. SSH Connection Issues:

   • Verify SSH key permissions (600 for private key)
   • Check if the server is accessible
   • Ensure the SSH user has proper permissions

2. Pipeline Failures:

   • Check GitLab CI/CD logs for detailed error messages
   • Verify environment variables are set correctly
   • Ensure the runner has the required tag

3. Deployment Script Issues:

   • Verify deploy.sh exists and is executable
   • Check if the path /home/fyfirman/vtuber-cretivox exists
   • Review deploy.sh logs for errors

Best Practices

1. Use dedicated deployment users on the server
2. Regularly rotate SSH keys
3. Keep deployment scripts idempotent
4. Add proper error handling in deployment scripts
5. Consider using environment-specific variables
6. Implement proper backup strategies

Security Considerations

1. Always use protected variables for sensitive data
2. Limit SSH key permissions to deployment needs
3. Use separate keys for different environments
4. Regularly audit access and permissions
5. Consider implementing IP whitelisting

Additional Resources

• GitLab CI/CD Documentation (opens in a new tab)
• SSH Documentation (opens in a new tab)
• Alpine Linux Documentation (opens in a new tab)