如何配置Debian GitLab的CI/CD

Prerequisites
Before configuring GitLab CI/CD on Debian, ensure you have:

• A Debian server (Debian 10/11 recommended) with root or sudo access.
• A GitLab project (self-hosted or GitLab.com) with code to manage.
• Basic familiarity with YAML syntax and CI/CD concepts (stages, jobs, runners).

Step 1: Install GitLab Runner (Self-Hosted Executor)
GitLab Runner is required to execute CI/CD jobs. On Debian, use the official repository for installation:

1. Add GitLab Runner Repository:

   curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
   

2. Install GitLab Runner:

   sudo apt install gitlab-runner
   

3. Register the Runner:
   • Retrieve the registration token from your GitLab project:
     Navigate to Project → Settings → CI/CD → Runners and copy the token.
   • Run the registration command (replace placeholders):

     sudo gitlab-runner register \
       --url https://gitlab.com/ \  # Use your GitLab instance URL (e.g., https://gitlab.com/ or your self-hosted domain)  
       --registration-token YOUR_REGISTRATION_TOKEN \  
       --executor shell \          # Choose an executor (shell for local execution, docker for containerized jobs)  
       --description "Debian Runner" \  
       --tag-list "ci,linux"       # Optional: Tags to filter jobs  
     

   • Follow prompts to complete registration.
4. Verify Runner Status:

   sudo gitlab-runner status
   

   The runner should show as “running”.

Step 2: Create .gitlab-ci.yml in Your Project Root
This file defines your CI/CD pipeline’s structure (stages, jobs, and steps). Below is a basic template for a Debian-based project (e.g., a Python or Java app):

# Define pipeline stages (executed in order)
stages:
  - build
  - test
  - deploy

# Variables (reusable across jobs)
variables:
  PROJECT_NAME: "my-debian-app"
  DOCKER_IMAGE: "my-registry/${PROJECT_NAME}:${CI_COMMIT_SHORT_SHA}"  # Dynamic image tag (commit SHA)

# Build Job (compiles/ packages code)
build_job:
  stage: build
  script:
    - echo "Building ${PROJECT_NAME}..."
    - ./build_script.sh  # Replace with your build command (e.g., mvn package, gradle build, or make)
  artifacts:  # Share build outputs with subsequent jobs
    paths:
      - target/*.jar  # Example: Java JAR file
      - dist/         # Example: Frontend build artifacts
    expire_in: 1 hour  # Auto-delete after 1 hour

# Test Job (runs automated tests)
test_job:
  stage: test
  script:
    - echo "Running tests..."
    - ./run_tests.sh  # Replace with your test command (e.g., mvn test, pytest, or npm test)
  needs: ["build_job"]  # Only run after build_job succeeds

# Deploy Job (deploys to production)
deploy_job:
  stage: deploy
  script:
    - echo "Deploying to production..."
    - scp target/*.jar user@production-server:/opt/apps/  # Example: Copy JAR to remote server
    - ssh user@production-server "systemctl restart my-app.service"  # Restart service (if applicable)
  only: ["main"]  # Trigger only on pushes/merges to 'main' branch
  needs: ["test_job"]  # Only run after test_job succeeds

Key Notes:

• Stages: Jobs in earlier stages (e.g., build) must succeed before later stages (e.g., deploy) run.
• Artifacts: Use artifacts to pass files (e.g., build outputs) between jobs.
• Tags: Use tags in jobs to restrict execution to specific runners (e.g., tags: ["debian", "docker"]).
• Conditional Execution: Use only/except to control when jobs run (e.g., only: ["main"] for production deploys).

Step 3: Configure SSH for Remote Deployment (Optional but Common)
If your deploy job interacts with a remote server (e.g., via scp/ssh), you need to securely store SSH credentials in GitLab CI/CD variables:

1. Generate SSH Keys (on your local machine):

   ssh-keygen -t rsa -b 4096 -C "gitlab-ci@debian-runner"
   

   • Save the key pair (e.g., id_rsa/id_rsa.pub) in ~/.ssh/.
2. Add Public Key to Remote Server:
   Copy the contents of id_rsa.pub and append it to ~/.ssh/authorized_keys on the production server.
3. Add Private Key to GitLab Variables:
   • Navigate to Project → Settings → CI/CD → Variables.
   • Click “Add variable”:
     • Key: SSH_PRIVATE_KEY
     • Value: Paste the contents of id_rsa (private key).
     • Type: File (optional but recommended for security).
4. Update .gitlab-ci.yml for SSH Access:
   Add this to the before_script of your deploy job (or a dedicated setup_ssh job):

   before_script:
     - 'which ssh-agent || ( apt-get update -y && apt-get install -y openssh-client )'  # Install ssh-agent if missing
     - eval $(ssh-agent -s)  # Start ssh-agent
     - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null  # Add private key
     - mkdir -p ~/.ssh  # Create .ssh directory
     - chmod 700 ~/.ssh  # Set correct permissions
     - ssh-keyscan production-server >> ~/.ssh/known_hosts  # Trust the server
     - chmod 644 ~/.ssh/known_hosts  # Set correct permissions
   

   Replace production-server with your server’s hostname/IP.

Step 4: Trigger the CI/CD Pipeline
Once configured, your pipeline will trigger automatically when you:

• Push code to the repository (e.g., git push origin main).
• Create a merge request.
• Manually trigger the pipeline from GitLab’s UI (CI/CD → Pipelines → Run pipeline).

To manually trigger (optional):

1. Navigate to your project’s CI/CD → Pipelines page.
2. Click “Run pipeline”.
3. Select the branch/commit and click “Run”.

Monitor Pipeline Execution:

• View pipeline status (CI/CD → Pipelines) and logs (Jobs) to debug failures.
• Click on a job to see real-time output (e.g., build/test logs).

Step 5: Optimize and Secure Your Pipeline

• Use Caching: Speed up builds by caching dependencies (e.g., Maven .m2 repo, Node.js node_modules). Example:

  cache:
    paths:
      - .m2/repository/  # Maven cache
      - node_modules/    # Node.js cache
    key: ${CI_COMMIT_REF_SLUG}  # Unique key per branch
  

• Use Docker Executor: For containerized jobs (e.g., building/pushing Docker images), switch the executor to docker and specify an image:

  build_job:
    stage: build
    image: maven:3.9-openjdk-17  # Use a Maven image from Docker Hub
    script:
      - mvn package
  

• Secure Sensitive Data: Store API keys, passwords, and tokens in GitLab CI/CD variables (mark them as “Protected” for sensitive environments like production).
• Limit Runner Resources: Configure resource limits (CPU/memory) for runners in /etc/gitlab-runner/config.toml (for self-hosted runners).

By following these steps, you’ll have a functional GitLab CI/CD pipeline on Debian that automates building, testing, and deploying your code. Adjust the .gitlab-ci.yml file to match your project’s language, framework, and deployment requirements.