Introduction

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

Features:

• 😃 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

Usage

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 }}"

How to use the action

The following inputs are available:

Parameter	Description	Default	Required
docker_compose_file_path	Set your docker compose file path with the CLI options.	-c docker-compose.yml -c docker-compose.prod.yml	false
env_file_base64	The base64 encoded .env file to load into the container.		false
log_level	The log level to use for the Docker CLI.	debug	false
md5_file_path	Set the path to the file you would like to get the MD5 checksum for.		false
md5_variable_name	Set the name of the variable to store the MD5 checksum in.	MD5_CHECKSUM	false
registry	Comma-separated list of container registries to authenticate with (e.g., "docker.io,ghcr.io").	docker.io	false
registry-token	The token or password to use to authenticate with the container registry.		⚠️ true
registry-username	The username to use to authenticate with the container registry.		⚠️ true
ssh_deploy_private_key	The private key you have authenticated to connect to your server via SSH.		⚠️ true
ssh_deploy_user	The user that you would like to connect as on the remote server via SSH.	deploy	⚠️ true
ssh_remote_hostname	The hostname or IP address of the server you want to connect to.		⚠️ true
ssh_remote_known_hosts	The public key of your SSH server to validate we are connecting to the right server.		false
ssh_remote_port	The SSH port of the remote server you would like to connect to.	22	false
stack_name	The name of your Docker stack.		⚠️ true

Working with SSH

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.

ssh_deploy_user

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).

ssh_remote_hostname

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.

ssh_remote_port

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.

ssh_deploy_private_key

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.

Warning

Be sure you're not copying hidden characters or extra whitespaces

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

Caution

In order for you to connect to your server, the user you're connecting as must have your public key in their authorized_keys file.

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

ssh_remote_known_hosts

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.

Removing the "ssh_remote_known_hosts" warning

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

Setting the "ssh_remote_known_hosts" secret

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:

Note

Replace myserver.example.com with the hostname of your server. You can also change the port by changing -p 22 to your desired port.

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).

Validate the known hosts file

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.

Advanced Usage

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

Getting the MD5 Checksum of a file

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.

Using an .env file

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 }}

Resources

• 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.

Contributing

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!

Our Sponsors

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.

Bronze Sponsors

No bronze sponsors yet. Become a sponsor →

Individual Supporters

    

About Us

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

Find us at:

• 📖 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.

Our products

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

⚡️ Starter Kits

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

📚 Books

• 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.

🛠️ Software-as-a-Service

• 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.

🌍 Open Source

• 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.