GitLab项目部署遇Permission Denied问题求助

Alright, let's break down how to fix that permission denied error you're hitting when deploying from GitLab to your staging and production servers—this is one of the most common hurdles with SSH-based deployments, but it's straightforward to resolve once you check the key pieces. Plus, I'll help you lock down the full deployment and rollback workflow to match your requirements.

Nearly all deployment permission errors boil down to misconfigured SSH keys or incorrect file/system permissions on your target servers. Let's walk through the fixes step by step:

1.1 Set Up SSH Key Pair Between GitLab Runner and Target Servers #

First, you need a trusted SSH connection between the GitLab Runner (the process executing your deployment jobs) and your staging/production servers:

• On the GitLab Runner machine, generate an SSH key pair (use ed25519 for better security, no passphrase so CI/CD can auto-authenticate):

  ssh-keygen -t ed25519 -C "gitlab-runner@your-gitlab-server"
  

• Copy the public key (~/.ssh/id_ed25519.pub) to your staging and production servers. Add it to the authorized_keys file of the deployment user (create a dedicated deploy user instead of using root for security):

  # On target server, as deploy user
  echo "PASTE_GITLAB_RUNNER_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys
  

• Fix permissions on the target server's SSH files (SSH is strict about these, and will reject connections if permissions are too open):

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/authorized_keys
  

1.2 Store the Private Key in GitLab CI/CD Variables #

You need to make the runner's private key available to your GitLab CI/CD jobs securely:

1. Go to your GitLab project → Settings → CI/CD → Variables
2. Add a new variable named SSH_PRIVATE_KEY
3. Paste the full content of the runner's private key (~/.ssh/id_ed25519) into the value field
4. Check Mask variable (hides the key in logs) and Protect variable (restricts it to protected branches like main)

1.3 Load the Key in Your CI/CD Pipeline #

Update your .gitlab-ci.yml to initialize SSH before running deployment commands:

deploy_staging:
  stage: deploy
  only:
    - main # Trigger only after merging to main
  before_script:
    - 'which ssh-agent || (apt-get update -y && apt-get install openssh-client -y)' # Install SSH client if missing
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - # Load the private key
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "StrictHostKeyChecking no" >> ~/.ssh/config # Skip first-time host verification (for staging; use host fingerprints in production)
  script:
    - ssh deploy@staging-server-ip "cd /path/to/your/app && git pull origin main && ./deploy-script.sh" # Replace with your actual deployment steps

1.4 Verify Target Server Permissions #

Ensure your deploy user has full access to your application directory:

# On target server
sudo chown -R deploy:deploy /path/to/your/app
sudo chmod -R 755 /path/to/your/app

Now that the permission issue is fixed, let's formalize your end-to-end workflow:

2.1 Staging Deployment (Auto-Triggered After Merge) #

Add this to your .gitlab-ci.yml to auto-deploy to staging whenever code is merged to main:

stages:
  - deploy_staging
  - deploy_production

deploy_staging:
  stage: deploy_staging
  only:
    - main
  before_script:
    # Reuse the SSH initialization steps from section 1.3
  script:
    - ssh deploy@staging-server "cd /var/www/staging-app && git fetch && git checkout main && git pull origin main && ./restart-app.sh"
    - echo "✅ Staging deployment completed successfully!"

2.2 Production Deployment (Manual Trigger for Safety) #

For production, use a manual trigger to avoid accidental deployments:

deploy_production:
  stage: deploy_production
  only:
    - main
  when: manual # Requires a user to click "Run" in GitLab
  before_script:
    # Reuse SSH initialization steps
  script:
    - ssh deploy@prod-server "cd /var/www/prod-app && git fetch && git checkout main && git pull origin main && ./restart-app.sh"
    - echo "✅ Production deployment completed successfully!"

2.3 Rollback Workflows (Manual Trigger) #

Add manual rollback jobs to revert changes on staging or production:

rollback_staging:
  stage: deploy_staging
  when: manual
  before_script:
    # Reuse SSH initialization steps
  script:
    # Use git revert for safe, history-preserving rollbacks (preferred)
    - ssh deploy@staging-server "cd /var/www/staging-app && git revert HEAD --no-edit && git push origin main"
    - ssh deploy@staging-server "cd /var/www/staging-app && ./restart-app.sh"
    - echo "🔄 Staging rolled back to previous version!"

rollback_production:
  stage: deploy_production
  when: manual
  before_script:
    # Reuse SSH initialization steps
  script:
    # For production, always use revert to keep commit history intact
    - ssh deploy@prod-server "cd /var/www/prod-app && git revert HEAD --no-edit && git push origin main"
    - ssh deploy@prod-server "cd /var/www/prod-app && ./restart-app.sh"
    - echo "🔄 Production rolled back to previous version!"

Note: If you need an emergency hard rollback (e.g., a broken commit you can't revert), replace git revert with git reset --hard HEAD~1—but only use this if you're sure you won't lose critical commit history, and communicate with your team afterward.

• If you still get permission errors, check the GitLab CI/CD job logs—they'll tell you if the issue is with SSH authentication or file permissions on the target server.
• Verify your target server's sshd_config file has PubkeyAuthentication yes enabled, and the AuthorizedKeysFile path matches ~/.ssh/authorized_keys.
• Test the SSH connection manually from the GitLab Runner machine: switch to the gitlab-runner user, then run ssh deploy@staging-server-ip to confirm you can log in without a password.

内容的提问来源于stack exchange，提问作者Sunil Kumar