This is a GitHub Action intended to simplify the deployment experience with GitHub Actions + Docker Swarm.

• 😃 Simple to use
• 🏗️ Bring your own container + configuration
• 💯 Replicate 100% of production from Development to CI to Deployment
• 💪 Use with self-hosted registries
• 🧮 Store MD5 hashes in environment variables for deployment
• 🔐 Use with private registries
• 🏠 Use .env files for deployment

Here is an example workflow:

name: Production Deployment
on:
  push:
    branches:
      - main

jobs:
  deploy:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - uses: serversideup/github-action-docker-swarm-deploy@v3
        with:
          ssh_deploy_private_key: "${{ secrets.SSH_DEPLOY_PRIVATE_KEY }}"
          ssh_remote_hostname: "${{ secrets.SSH_REMOTE_HOSTNAME }}"
          registry: "ghcr.io"
          registry-username: "${{ github.actor }}"
          registry-token: "${{ secrets.GITHUB_TOKEN }}"
          stack_name: "${{ env.PROJECT_NAME }}"
          md5_file_path: "./.infrastructure/conf/traefik/prod/traefik.yml"
          md5_variable_name: "SPIN_MD5_HASH_TRAEFIK_YML"
          env_file_base64: "${{ secrets.ENV_FILE_BASE64 }}"

The following inputs are available:

SSH can have a few moving parts and it's important you get this right. Here's a few pointers to ensure you have the right setup.

This is the user you want to connect to your server with. This is most likely going to be deploy but could be different depending on your setup. It is very important that whatever user you choose, this user should have permissions to run docker stack deploy (without sudo).

This is the hostname or IP address of your server. This is most likely going to be your server's public IP address. This can be 1.2.3.4 or myserver.example.com.

This is the port of your SSH server. This is most likely going to be 22 but could be different depending on your setup. Make sure this port is accessible from GitHub Actions. You may have to allow this port through your router, firewall, or security policy with your hosting provider.

This is the private key you use to authenticate to your server via SSH. It must be in a valid private key format.

To generate a keypair, you can use the following commands:

ssh-keygen -o -a 100 -t ed25519 -f ~/Desktop/id_ed25519_deploy -C deploy

This will create two files on your desktop. You can use cat to get the content of your files.

cat ~/Desktop/id_ed25519_deploy # Get the content of your PRIVATE key
cat ~/Desktop/id_ed25519_deploy.pub # Get the content of your PUBLIC key

## If you use macOS, you can use `pbcopy` to copy your key to your clipboard

cat ~/Desktop/id_ed25519_deploy | pbcopy # Copy your private key to your clipboard
cat ~/Desktop/id_ed25519_deploy.pub | pbcopy # Copy your public key to your clipboard

Copy the output and add it to the ~/.ssh/authorized_keys file on your server for the user you're connecting as.

This is the public key of your SSH server to validate we are connecting to the right server. It must be in a valid known_hosts format.

For simplicity sake, we will automatically scan the known public SSH keys of your server and attempt to make a connection. The problem with this is it opens you up to a man-in-the-middle attack.

To ensure you're validating the identity of your server, you can set the ssh_remote_known_hosts input with the public key of your server. You can set this value to a GitHub secret like SSH_REMOTE_KNOWN_HOSTS:

- uses: serversideup/github-action-docker-swarm-deploy@v3
  with:
    registry-token: "${{ secrets.GITHUB_TOKEN }}"
    registry-username: "${{ github.actor }}"
    ssh_deploy_private_key: "${{ secrets.SSH_DEPLOY_PRIVATE_KEY }}"
    ssh_remote_hostname: "${{ secrets.SSH_REMOTE_HOSTNAME }}"
    ssh_remote_known_hosts: "${{ secrets.SSH_REMOTE_KNOWN_HOSTS }}" # Set "SSH_REMOTE_KNOWN_HOSTS" in GitHub Actions Secrets 
    stack_name: "${{ env.PROJECT_NAME }}"
  env:
    SPIN_IMAGE_DOCKERFILE_PHP: "ghcr.io/${{ github.repository }}:${{ github.sha }}"
    SPIN_DEPLOYMENT_ENVIRONMENT: production

You can set the ssh_remote_known_hosts secret by getting the public key of your server and setting it as a GitHub secret. You can run this from your local machine (not in GitHub Actions) to get the public key of your server:

ssh-keyscan -p 22 -H myserver.example.com 2>/dev/null | sort -u

The output will look similar to this, with hashed hostnames:

|1|BfvcToAPMeAK0zR9FShCnP5CCaw=|ltUazkjjoIKsoBFQMF5yOTJt/Ks= ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBKIAz4U9GvgyBttgCnvi4AfBq3CdQ9XqAryrIyO1O60
|1|J/BpMKspk0BwPAxR28Dzc7gVGgw=|RAimV4/7iS4jlmFmDAfex/nKDUQ= ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQChvNZNpcjdSXJWVdnhieQXRgBVUUwpexLz0dbDegUj68vrzXsgtrnGtf+sJlRhI6C7jBZDfxk2jXL1ASfxEQUqbvptZTG68uusD1DYx3wtb/kTqvJ3JkFuWJbt2zLyZktPrueHA9cvuquW46M6wSZN5AZddNitUZ09Bpb+dTVZkjbEDOiGoHRDj5M86e1rr/8UGNrAVZl/hckup3lfu3B3P0LKnGnMw+/DXIKvJiwVJ3OdHzyq6D/x9uNgcOUA7UPgUbV30gyFtWr2Az6Vn/ZolDOGasK9iI5WjvBdXwyWNwEnnR539RutiwbS/XTnb0Jj/fFS5NM2/AM3nCT37D4uQA7aJFka7keUTJZJIVanziz9Ty76lloweLDKHN2CyvUijjSx5HaqV9Dr2nTefTPPvzz1D9xU0WJX8KC77Wcu8qEjqSwNihJqucXQvq4xeBZ85OGPbvzAFYqZdjynzVsLP50E7kmdaW3VJx88hbg+vyXrJD1urcOVPNtGoMpN2Mc=
|1|cYUT42KbDx+rQD0YSpKgDxbFWBc=|D13n4gWdMyJ+C2nifoEEeFmezmE= ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBN7wgADkhTHi7WER2pCZ5/10HBmhSIAq9zS1rWiBG5A8t2ATh5QnJ17XtPKXEJGPH8nogry/bZ+WKxI4zojGD+Q=

Copy the output and set it as a GitHub secret (usually called SSH_REMOTE_KNOWN_HOSTS).

If you need to validate the known hosts file, you can save it in a file on your local machine and attempt to SSH into your server with it:

ssh -p 22 -i /path/to/test_known_hosts_file myserver.example.com

If you cannot connect from your local machine, then you know there is an issue with the known hosts file itself.

We also have some helpful features for our power users out there.

We include an optional input to get the MD5 checksum of a file. This is useful if you're working with Docker Configs and you only want the service to update if the file has changed. You just need to set the following inputs (a full example is available at the top of this document):

steps:
  - uses: serversideup/github-action-docker-swarm-deploy@v3
    with:
      md5_file_path: "./path/to/my/file.txt"
      md5_variable_name: "MY_FILE_MD5"

This will store the MD5 checksum of the file at ./path/to/my/file.txt in the environment variable MY_FILE_MD5.

You can use an .env file to set environment variables for your container. This is useful if you're working with environment variables that are different for each environment. You can set the .env file as a base64 encoded string and it will be decoded and loaded into the container.

steps:
  - uses: serversideup/github-action-docker-swarm-deploy@v3
    with:
      env_file_base64: "${{ secrets.ENV_FILE_BASE64 }}"

To set the value of ENV_FILE_BASE64, you can use the following command:

cat .env | base64

Any variable set in the .env file will be available to the deployment to be used in your docker-compose.yml file.

For example, if you have a .env file with the following:

DB_HOST=mysql
DB_PORT=3306
DB_USER=root
DB_PASSWORD=password

Then you can use the following in your docker-compose.yml file:

services:
  mysql:
    environment:
      - DB_HOST=${{ env.DB_HOST }}
      - DB_PORT=${{ env.DB_PORT }}
      - DB_USER=${{ env.DB_USER }}
      - DB_PASSWORD=${{ env.DB_PASSWORD }}

• Discord for friendly support from the community and the team.
• GitHub for source code, bug reports, and project management.
• Get Professional Help - Get video + screen-sharing help directly from the core contributors.

As an open-source project, we strive for transparency and collaboration in our development process. We greatly appreciate any contributions members of our community can provide. Whether you're fixing bugs, proposing features, improving documentation, or spreading awareness - your involvement strengthens the project. Please review our contribution guidelines and code of conduct to understand how we work together respectfully.

• Bug Report: If you're experiencing an issue while using this action, please create an issue.
• Feature Request: Make this project better by submitting a feature request.
• Documentation: Improve our documentation by submitting a documentation change.
• Community Support: Help others on Discord.
• Security Report: Report critical security issues via our responsible disclosure policy.

Need help getting started? Join our Discord community and we'll help you out!

All of our software is free an open to the world. None of this can be brought to you without the financial backing of our sponsors.

We're Dan and Jay - a two person team with a passion for open source products. We created Server Side Up to help share what we learn.

Dan Pastori	Jay Rogers

• 📖 Blog - Get the latest guides and free courses on all things web/mobile development.
• 🙋 Community - Get friendly help from our community members.
• 🤵‍♂️ Get Professional Help - Get video + screen-sharing support from the core contributors.
• 💻 GitHub - Check out our other open source projects.
• 📫 Newsletter - Skip the algorithms and get quality content right to your inbox.
• 🐥 Twitter - You can also follow Dan and Jay.
• ❤️ Sponsor Us - Please consider sponsoring us so we can create more helpful resources.

If you appreciate this project, be sure to check out our other projects.

• Spin Pro: Laravel Sail alternative for running Docker from development → production.

• The Ultimate Guide to Building APIs & SPAs: Build web & mobile apps from the same codebase.
• Building Multi-Platform Browser Extensions: Ship extensions to all browsers from the same codebase.

• Bugflow: Get visual bug reports directly in GitHub, GitLab, and more.
• SelfHost Pro: Connect Stripe or Lemonsqueezy to a private docker registry for self-hosted apps.

• AmplitudeJS: Open-source HTML5 & JavaScript Web Audio Library.
• Spin: Laravel Sail alternative for running Docker from development → production.
• Financial Freedom: Open source alternative to Mint, YNAB, & Monarch Money.