{"id":26962280,"url":"https://github.com/alcharra/docker-deploy-action","last_synced_at":"2025-04-03T05:19:38.995Z","repository":{"id":282486465,"uuid":"941717039","full_name":"alcharra/docker-deploy-action","owner":"alcharra","description":"GitHub Action for deploying Docker Compose or Swarm over SSH β€” supports file upload, Docker network management, service health checks, rollback and cleanup.","archived":false,"fork":false,"pushed_at":"2025-03-28T01:28:28.000Z","size":34,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T02:20:01.956Z","etag":null,"topics":["bash","docker","gituhb-actions","powershell","scp","ssh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alcharra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-02T23:19:37.000Z","updated_at":"2025-03-28T01:55:06.000Z","dependencies_parsed_at":"2025-03-14T23:28:35.672Z","dependency_job_id":"fc1ede23-476d-45ae-aa8e-2f07c562fa41","html_url":"https://github.com/alcharra/docker-deploy-action","commit_stats":null,"previous_names":["alcharra/docker-deploy-action"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcharra%2Fdocker-deploy-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcharra%2Fdocker-deploy-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcharra%2Fdocker-deploy-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcharra%2Fdocker-deploy-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alcharra","download_url":"https://codeload.github.com/alcharra/docker-deploy-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246939657,"owners_count":20857999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","docker","gituhb-actions","powershell","scp","ssh"],"created_at":"2025-04-03T05:19:38.368Z","updated_at":"2025-04-03T05:19:38.987Z","avatar_url":"https://github.com/alcharra.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐳 Docker Deploy Action\n\n[![Deploy Test](https://github.com/alcharra/docker-deploy-action/actions/workflows/deploy-test.yml/badge.svg)](https://github.com/alcharra/docker-deploy-action/actions/workflows/deploy-test.yml)\n[![GitHub tag](https://img.shields.io/github/tag/alcharra/docker-deploy-action.svg)](https://github.com/alcharra/docker-deploy-action-go/releases)\n[![ShellCheck](https://github.com/alcharra/docker-deploy-action/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/alcharra/docker-deploy-action/actions/workflows/shellcheck.yml)\n\nA **production-ready** GitHub Action for deploying **Docker Compose** or **Docker Swarm** services over SSH. \n\nThis action securely **uploads deployment files**, ensures the **target server is ready** and **automates network creation** if needed. It deploys services with **health checks, rollback support and optional cleanup** to keep your infrastructure stable.\n\n\u003e [!NOTE] \n\u003e A faster, lightweight alternative built with Go is now available! \n\u003e Check out [docker-deploy-action-go](https://github.com/alcharra/docker-deploy-action-go) - same features, better performance πŸš€ \n\u003e πŸ› οΈ **This action will continue to be actively maintained and updated.**\n\n## What This Action Brings You\n\nThis GitHub Action makes your Docker deployments smooth, secure and reliable β€” whether you’re using Docker Compose or Swarm. Here's what you get out of the box:\n\n- **πŸ“‚ Flexible Deployments:** Deploy Docker Compose or Swarm stacks seamlessly over SSH to any Linux server.\n- **πŸ› οΈ Smart Setup:** Automatically creates the target project directory with the correct permissions and ownership.\n- **πŸ“¦ Full Config Support:** Upload multiple config and environment files (`.env`, secrets, YAML, etc.) effortlessly.\n- **πŸ”‘ Private Registry Access:** Supports secure login to private registries like Docker Hub and GHCR.\n- **🌐 Network Intelligence:** Ensures required Docker networks exist or creates them automatically with your chosen driver.\n- **🩺 Health-First Deployments:** Built-in health checks confirm services are running and stable after deployment.\n- **♻️ Auto-Rollback on Failures:** \n - **Swarm:** Uses Docker's native `--rollback` feature. \n - **Compose:** Restores the last known working deployment file.\n- **🧹 Optional Cleanup:** Reclaim disk space with Docker pruneβ€”configurable by type.\n- **πŸ“œ Transparent Logs:** Get structured logs for every step β€” from file transfers to health checks.\n- **πŸ›‘οΈ Built-In Security:** SSH keys are securely handled and wiped after deployment to keep your infrastructure safe.\n- **πŸš€ Fast Automation:** No need for manual SSH commands β€” just push to GitHub and deploy!\n\n## Inputs\n\n| Input Parameter | Description | Required | Default Value |\n| --------------------------- | ---------------------------------------------------------------------------------------------------- | :------: | -------------------- |\n| `ssh_host` | Hostname or IP address of the target server | βœ… | |\n| `ssh_port` | Port used for the SSH connection | ❌ | `22` |\n| `ssh_user` | Username used for the SSH connection | βœ… | |\n| `ssh_key` | Private SSH key for authentication | βœ… | |\n| `ssh_key_passphrase` | Passphrase for the encrypted SSH private key | ❌ | |\n| `ssh_known_hosts` | Contents of the SSH `known_hosts` file used to verify the server's identity | ❌ | |\n| `fingerprint` | SSH host fingerprint for verifying the server's identity (SHA256 format) | ❌ | |\n| `timeout` | SSH connection timeout in seconds (e.g. `10`, `30`, `60`) | ❌ | `10` |\n| `project_path` | Path on the server where files will be uploaded | βœ… | |\n| `deploy_file` | Path to the file used for defining the deployment (e.g. Docker Compose) | βœ… | `docker-compose.yml` |\n| `extra_files` | Comma-separated list of additional files to upload (e.g. .env, config.yml) | ❌ | |\n| `mode` | Deployment mode (`compose` or `stack`) | ❌ | `compose` |\n| `stack_name` | Stack name used during Swarm deployment (required if mode is `stack`) | ❌ | |\n| `compose_pull` | Whether to pull the latest images before bringing up services with Docker Compose (`true` / `false`) | ❌ | `true` |\n| `compose_build` | Whether to build images before starting services with Docker Compose (`true` / `false`) | ❌ | `false` |\n| `compose_no_deps` | Whether to skip starting linked services (dependencies) with Docker Compose (`true` / `false`) | ❌ | `false` |\n| `compose_target_services` | Comma-separated list of services to restart (e.g. web,db) - Restarts all if unset | ❌ | |\n| `docker_network` | Name of the Docker network to be used or created if missing | ❌ | |\n| `docker_network_driver` | Driver for the network (`bridge`, `overlay`, `macvlan`, etc.) | ❌ | `bridge` |\n| `docker_network_attachable` | Whether standalone containers can attach to the network (`true` / `false`) | ❌ | `false` |\n| `docker_prune` | Type of Docker resource prune to run after deployment | ❌ | `none` |\n| `registry_host` | Host address for the registry or remote service requiring authentication | ❌ | |\n| `registry_user` | Username for authenticating with the registry or remote service | ❌ | |\n| `registry_pass` | Password or token for authenticating with the registry or remote service | ❌ | |\n| `enable_rollback` | Whether to enable automatic rollback if deployment fails (`true` / `false`) | ❌ | `false` |\n| `env_vars` | Environment variables to write to a `.env` file and upload to the server | ❌ | |\n\n## SSH Host Key Verification\n\nThis tool supports two secure options for verifying the SSH server's identity during deployment:\n\n- Providing a `known_hosts` entry (OpenSSH-compatible format)\n- Supplying the server's SSH key `fingerprint` (a single-line public key)\n\nYou only need to provide one of these β€” not both.\n\n\u003e [!WARNING] \n\u003e If neither `ssh_known_hosts` nor `fingerprint` is specified, the tool will fall back to scanning the server key using `ssh-keyscan`. \n\u003e While this avoids prompts during automation, it does not confirm the authenticity of the host key. \n\u003e This approach is not secure and should not be used in production environments.\n\n\u003e [!IMPORTANT] \n\u003e For a secure deployment, always provide either a `known_hosts` entry or a `fingerprint`. \n\u003e This helps ensure that the connection is made to the correct server and prevents impersonation.\n\n\u003e [!TIP] \n\u003e Use `ssh_known_hosts` for full compatibility with OpenSSH and to support multiple key types. \n\u003e Use `fingerprint` for a simpler, one-line setup if connecting to a single known host. \n\u003e In either case, store the value securely using a GitHub environment variable or secret.\n\n## Supported Prune Types\n\n- `none` - No pruning (default)\n- `system` - Remove unused images, containers, volumes and networks\n- `volumes` - Remove unused volumes\n- `networks` - Remove unused networks\n- `images` - Remove unused images\n- `containers` - Remove stopped containers\n\n## Network Management\n\nThis action ensures the required Docker network exists before deploying. If it is missing, it will be created automatically using the specified driver.\n\n### How it works\n\n- If the network already exists, its driver is verified.\n- If the network does not exist, it is created using the provided driver.\n- If `docker_network_attachable` is set to `true`, the network is created with the `--attachable` flag.\n- In `stack` mode with the `overlay` driver:\n - Swarm mode must be active on the target server.\n - A warning is displayed if Swarm is not active.\n- If the existing network uses a different driver than specified, a warning is displayed.\n\n### Network scenarios\n\nA network will be created if:\n\n- The specified network does not exist.\n- A custom network is defined via `docker_network`.\n- The provided driver is valid and supported.\n\nWarnings will be displayed if:\n\n- The existing network's driver does not match the one specified.\n- Swarm mode is inactive but `overlay` is requested in `stack` mode.\n\n### Example usage\n\n```yaml\ndocker_network: my_network\ndocker_network_driver: overlay\ndocker_network_attachable: true\n```\n\n## Rollback Behaviour\n\nThis action supports automatic rollback if a deployment fails to start correctly.\n\n### How it works\n\n- In `stack` mode:\n\n - Docker Swarm’s built-in rollback is used.\n - The command `docker service update --rollback \u003cservice-name\u003e` is run to revert services in the stack to the last working state.\n\n- In `compose` mode:\n - A backup of the current deployment file is created before deployment.\n - If services fail to start, the backup is restored and Compose is re-deployed.\n - If rollback is successful, the backup file is removed to avoid stale data.\n\n### Rollback triggers\n\nRollback will occur if:\n\n- Services fail health checks.\n- Containers immediately exit after starting.\n- Docker returns an error during service startup.\n\nRollback will not occur if:\n\n- The deployment succeeds but the application has internal errors.\n- A service is manually stopped by the user.\n- Rollback is disabled via `enable_rollback: false`.\n\n## Example Workflow\n\n```yaml\nname: Deploy\n\non:\n push:\n branches:\n - main\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n\n steps:\n - name: πŸ“¦ Checkout repository\n uses: actions/checkout@v4\n\n # 🐳 Example 1: Deploy using Docker Stack (Swarm Mode)\n - name: πŸš€ Deploy using Docker Stack\n uses: alcharra/docker-deploy-action@v2\n with:\n # SSH Connection\n ssh_host: ${{ secrets.SSH_HOST }} # Remote server IP or hostname\n ssh_user: ${{ secrets.SSH_USER }} # SSH username\n ssh_key: ${{ secrets.SSH_KEY }} # Private SSH key\n ssh_key_passphrase: ${{ secrets.SSH_KEY_PASSPHRASE }} # (Optional) SSH key passphrase\n ssh_known_hosts: ${{ secrets.SSH_KNOWN_HOSTS }} # (Optional) known_hosts entry\n\n # Deployment Settings\n project_path: /opt/myapp # Remote directory for upload and deploy\n deploy_file: docker-stack.yml # Stack file to deploy\n mode: stack # Deployment mode: 'stack'\n stack_name: myapp # Stack name on the target host\n\n # Additional Files\n extra_files: traefik.yml # Upload additional files (e.g. configs)\n\n # Docker Network Settings\n docker_network: myapp_network # Network name to use or create\n docker_network_driver: overlay # Network driver (e.g. bridge, overlay)\n\n # Post-Deployment Cleanup\n docker_prune: system # Prune unused Docker resources\n\n # Registry Authentication\n registry_host: ghcr.io\n registry_user: ${{ github.actor }}\n registry_pass: ${{ secrets.GITHUB_TOKEN }}\n\n # 🐳 Example 2: Deploy using Docker Compose\n - name: πŸš€ Deploy using Docker Compose\n uses: alcharra/docker-deploy-action@v2\n with:\n # SSH Connection\n ssh_host: ${{ secrets.SSH_HOST }}\n ssh_user: ${{ secrets.SSH_USER }}\n ssh_key: ${{ secrets.SSH_KEY }}\n fingerprint: ${{ secrets.SSH_FINGERPRINT }} # (Optional) SHA256 host fingerprint\n\n # Deployment Settings\n project_path: /opt/myapp\n deploy_file: docker-compose.yml\n mode: compose\n\n # Environment Variables \n env_vars: |\n DB_HOST=localhost\n DB_USER=myuser\n DB_PASS=${{ secrets.DB_PASS }}\n\n # Additional Files\n extra_files: database.env,nginx.conf # Upload environment and config files\n\n # Compose Behaviour\n compose_pull: true # Pull latest images before up\n compose_build: true # Build images before starting services\n compose_no_deps: true # Don’t start linked services\n compose_target_services: web,db # Restart only selected services (optional)\n\n # Rollback Support\n enable_rollback: true # Automatically rollback on failure\n\n # Docker Network\n docker_network: myapp_network\n docker_network_driver: bridge\n\n # Post-Deployment Cleanup\n docker_prune: volumes\n```\n\n## Requirements on the Server\n\n- Docker must be installed\n- Docker Compose (if using `compose` mode)\n- Docker Swarm must be initialised (if using `stack` mode)\n- SSH access must be configured for the provided user and key\n\n## Important Notes\n\n- This action is designed for Linux servers (Debian, Ubuntu, Alpine, CentOS)\n- The SSH user must have permissions to write files and run Docker commands\n- If the `project_path` does not exist, it will be created with permissions `750` and owned by the provided SSH user\n- If using Swarm mode, the target machine must be a Swarm manager\n\n## References\n\n- [Docker Compose Documentation](https://docs.docker.com/compose/)\n- [Docker Swarm Documentation](https://docs.docker.com/engine/swarm/)\n- [Docker Prune Documentation](https://docs.docker.com/config/pruning/)\n- [Docker Network Documentation](https://docs.docker.com/network/)\n\n## Tips for Maintainers\n\n- Test the full process locally before using in GitHub Actions\n- Always use GitHub Secrets for sensitive values like SSH keys\n- Make sure firewall rules allow SSH access from GitHub runners\n\n## Contributing\n\nContributions are welcome. If you would like to improve this action, please feel free to open a pull request or raise an issue. I appreciate your input.\n\n## Feature Requests\n\nHave an idea or need something this action doesn't support yet? \nPlease [start a discussion](https://github.com/alcharra/docker-deploy-action/discussions/new?category=ideas) under the **Ideas** category.\n\nThis helps keep feature requests organised and visible to others who may want the same thing.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcharra%2Fdocker-deploy-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falcharra%2Fdocker-deploy-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcharra%2Fdocker-deploy-action/lists"}