If you've ever tried to set up continuous deployment to a remote Docker host, you know the pain. GitHub Actions is great for CI — build, test, done. But deploying to a remote server? That's where things get messy.

Most tutorials hand you a 200-line shell script with ssh hacks, scp gymnastics, and prayer. I got tired of that, so I packaged it into a reusable GitHub Action that handles Docker Compose and Docker Swarm deployments over SSH.

Here's how it works and how to set it up in under 10 minutes.

The Problem

You have a VPS (or a bare-metal server) running Docker. You want GitHub Actions to:

1. Build your images (or pull them from a registry)
2. SSH into your server
3. Deploy using docker-compose up or docker stack deploy
4. Clean up old files

Without leaking SSH keys everywhere or writing bespoke deployment scripts per project.

The Action: docker-remote-deployment-action

github.com/sulthonzh/docker-remote-deployment-action

It's a GitHub Action available on the Marketplace that does exactly this. It supports two deployment modes:

• docker-compose — runs docker-compose on the remote host
• docker-swarm — runs docker stack deploy for Swarm services

Both via SSH, both from your existing docker-compose.yml.

The Minimal Setup

1. Add your SSH keys to GitHub Secrets

In your repo → Settings → Secrets and variables → Actions, add:

• SSH_PRIVATE_KEY — your private key for the server
• SSH_PUBLIC_KEY — the corresponding public key

2. Create the workflow file

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy to server
        uses: sulthonzh/docker-remote-deployment-action@v1
        with:
          remote_docker_host: deploy@your-server.com
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
          deployment_mode: docker-compose
          stack_file_name: docker-compose.yml
          args: up -d

Push to main → your service deploys. That's it.

Docker Swarm Mode

If you're running a Swarm cluster, switch the mode and add the stack name:

- name: Deploy to Swarm
  uses: sulthonzh/docker-remote-deployment-action@v1
  with:
    remote_docker_host: deploy@your-server.com
    ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
    ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
    deployment_mode: docker-swarm
    copy_stack_file: true
    deploy_path: /opt/deployments/myapp
    stack_file_name: docker-compose.yaml
    keep_files: 5
    args: myapp

This will:

1. Copy your docker-compose.yaml to /opt/deployments/myapp/ on the server
2. Run docker stack deploy -c docker-compose.yaml myapp
3. Keep the last 5 deployment files (auto-cleanup old ones)

Feature Breakdown

copy_stack_file: true — Deploy from the server

When enabled, the Action copies your compose file to a configurable path on the remote host before deploying. This is useful when:

• Your compose file references local build contexts
• You want deployment history on the server
• You need to inspect the compose file on the host later

Combined with keep_files: N, it auto-prunes old deployment directories. No manual cleanup.

pull_images_first: true — Pull before deploy

If your compose file references images from a private registry:

pull_images_first: true
docker_registry_username: ${{ secrets.REGISTRY_USER }}
docker_registry_password: ${{ secrets.REGISTRY_PASS }}

The Action logs into your registry and pulls images before deploying. Works with any Docker-compatible registry.

docker_prune: true — Automatic cleanup

Adds a docker system prune -f after deployment. Useful on small VPS instances where disk space is precious.

pre_deployment_command_args — Run commands before deploy

Need to run migrations or health checks before deploying?

pre_deployment_command_args: "docker exec myapp_web bundle exec rake db:migrate"

Runs any command on the remote host before the deployment step.

A Real-World Example: Full Pipeline

Here's a complete workflow that builds, pushes, and deploys:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: myuser/myapp:${{ github.sha }}

      - name: Update image tag in compose file
        run: |
          sed -i "s|image: myuser/myapp:.*|image: myuser/myapp:${{ github.sha }}|" docker-compose.yml

      - name: Deploy
        uses: sulthonzh/docker-remote-deployment-action@v1
        with:
          remote_docker_host: deploy@myserver.com
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
          deployment_mode: docker-compose
          copy_stack_file: true
          deploy_path: /opt/myapp
          stack_file_name: docker-compose.yml
          keep_files: 3
          pull_images_first: true
          docker_registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
          docker_registry_password: ${{ secrets.DOCKERHUB_TOKEN }}
          args: up -d --remove-orphans

This gives you a full CI/CD pipeline: commit → build → push → deploy. No Jenkins, no GitLab Runner, no self-hosted agent. Just GitHub Actions SSHing into your server.

Security Notes

A few things to keep in mind:

• Use a dedicated deploy user on your server, not root. Create a user that only has Docker permissions.
• Restrict SSH keys — the deploy key should only work for Docker-related commands.
• Use GitHub Secrets — never hardcode keys in your workflow files.
• Rotate keys if they ever appear in logs (the Action masks secrets, but be careful with set -x in pre-deployment commands).

When This Shines

This setup is ideal for:

• Solo devs / small teams deploying to a single VPS
• Side projects that don't need Kubernetes
• Staging environments that auto-deploy on push
• Hobby infrastructure where you want CI/CD without the complexity of ArgoCD or Flux

If you're running 50 microservices on EKS, this isn't for you. If you're deploying a few containers to a $5/month DigitalOcean droplet, this is exactly what you need.

What's Next

The Action is stable and production-ready at v1.0.0. It's adapted from earlier work by wshihadeh and TapTap21, with improvements for modern GitHub Actions.

Star it, try it, open issues if something doesn't work. That's how open source grows.

Built this while deploying side projects at quadbyte. More dev tools coming.