From 2530ba2adaef03f9c92c6d3dc4a3abbaeb9eeff6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Fri, 2 Oct 2026 10:10:51 -0300 Subject: [PATCH 1/5] Fix broken instructions and adjust section heading levels in README - Fix `.github/actions` to `.github/workflows` in GitHub Action usage instructions - Add line continuations to docker run example so it can be pasted as a shell command - Change registry from `hub.docker.com` to `docker.io` (correct Docker API endpoint) - Fix typo `.gitlab-cy.yml` to `.gitlab-ci.yml` - Fix typo `varibles` to `variables` in GitLab CI example - Update outdated docker:20.10.16-dind to docker:26-dind - Adjust "A note on whitespace" section from ### to ## level (was incorrectly nested under Configuration options table) --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f3c60ef..4f927ca 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ GitHub Action and Docker image used to deploy a Docker stack on a Docker Swarm. | `debug` | `DEBUG` | Verbose logging | | **0** | | `scale_after` | `SCALE_AFTER` | Scale a service after a deployment has converged successfully. Example: servicename=1 | | | -### A note on whitespace +## A note on whitespace `registry`, `username`, `remote_host`, `remote_port` and `remote_user` cannot contain whitespace, so any is removed before the value is used, and a line @@ -142,7 +142,7 @@ case of `env_file` with a name you cannot choose. Prefer `env_file` or ## Using the GitHub Action -Add, or edit an existing, `yaml` file inside `.github/actions` and use the configuration options listed above. +Add, or edit an existing, `yaml` file inside `.github/workflows` and use the configuration options listed above. ### Examples @@ -219,7 +219,7 @@ It is possible to directly use the `ghcr.io/kitconcept/docker-stack-deploy` Dock Considering you have a local file named `.env_deploy` with content: ``` -REGISTRY=hub.docker.com +REGISTRY=docker.io USERNAME=foo_usr PASSWORD=averylargepasswordortoken REMOTE_HOST=192.168.17.2 @@ -232,11 +232,11 @@ DEBUG=1 Run the following command: ```shell -docker run --rm - -v "$(pwd)":/github/workspace - -v /var/run/docker.sock:/var/run/docker.sock - --env-file=.env_deploy - -e REMOTE_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" +docker run --rm \ + -v "$(pwd)":/github/workspace \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --env-file=.env_deploy \ + -e REMOTE_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)" \ ghcr.io/kitconcept/docker-stack-deploy:latest ``` @@ -244,20 +244,20 @@ docker run --rm On your GitLab project, go to `Settings -> CI/CD` and add the environment variables under **Variables**. -Then edit your `.gitlab-cy.yml` to include the `deploy` step: +Then edit your `.gitlab-ci.yml` to include the `deploy` step: ```yaml image: busybox:latest services: - - docker:20.10.16-dind + - docker:26-dind before_script: - docker info deploy: stage: deploy - varibles: + variables: REGISTRY: ${REGISTRY} USERNAME: ${REGISTRY_USER} PASSWORD: ${REGISTRY_PASSWORD} From 26299636ad597db02dcd045f293c6f489eef66ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Fri, 2 Oct 2026 10:11:15 -0300 Subject: [PATCH 2/5] Polish README formatting and accuracy improvements - Fix registry input table to have consistent column count (add missing default value column) - Fix "on the the machine" typo to "on the machine" - Add blank line before License section for better readability - Update Credits section to accurately describe docker-stack-wait as a maintained fork rather than external script --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4f927ca..9426ffe 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,11 @@ GitHub Action and Docker image used to deploy a Docker stack on a Docker Swarm. | GitHub Action Input | Environment Variable | Summary | Required | Default Value | | --- | --- | --- | --- | --- | -| `registry` | `REGISTRY` | Specify which container registry to login to. | | +| `registry` | `REGISTRY` | Specify which container registry to login to. | | | | `username` | `USERNAME` | Container registry username. | | | | `password` | `PASSWORD` | Container registry password. | | | | `remote_host` | `REMOTE_HOST` | Hostname or address of the machine running the Docker Swarm manager node | ✅ | | -| `remote_port` | `REMOTE_PORT` | SSH port to connect on the the machine running the Docker Swarm manager node. | | **22** | +| `remote_port` | `REMOTE_PORT` | SSH port to connect on the machine running the Docker Swarm manager node. | | **22** | | `remote_user` | `REMOTE_USER` | User with SSH and Docker privileges on the machine running the Docker Swarm manager node. | ✅ | | | `remote_private_key` | `REMOTE_PRIVATE_KEY` | Private key used for ssh authentication. | ✅ | | | `deploy_timeout` | `DEPLOY_TIMEOUT` | Seconds, to wait until the deploy finishes | | **600** | @@ -347,9 +347,10 @@ request that genuinely needs no entry can carry the `skip changelog` label. [![kitconcept GmbH](https://raw.githubusercontent.com/kitconcept/docker-stack-deploy/main/docs/kitconcept.png)](https://kitconcept.com) -This repository also uses the `docker-stack-wait` script, available at [GitHub](https://github.com/sudo-bmitch/docker-stack-wait). +This repository includes a maintained fork of the `docker-stack-wait` script, originally from [GitHub](https://github.com/sudo-bmitch/docker-stack-wait). The logo is based on [rocket icon](https://freeicons.io/seo/rocket-icon-24668#). + ## License The project is licensed under [MIT License](./LICENSE) From 6ad185fd2d1790ee1805c4d2b8545a763442fd65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Fri, 2 Oct 2026 10:11:39 -0300 Subject: [PATCH 3/5] Add comprehensive documentation for optional parameters and prerequisites - Add Prerequisites section explaining Docker Swarm, SSH setup, and Docker group requirements - Add Optional Parameters section with detailed explanations for deploy_timeout, resolve_image, prune, and scale_after - Document that registry login is skipped when credentials are not provided - Include practical examples for each optional parameter showing real-world usage --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/README.md b/README.md index 9426ffe..c69ba01 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,17 @@ GitHub Action and Docker image used to deploy a Docker stack on a Docker Swarm. +## Prerequisites + +To use this action or Docker image, you need the following: + +- A Docker Swarm manager node reachable over SSH from the GitHub runner or Docker host +- SSH credentials: the private key corresponding to a user account on the Swarm manager node +- The user account must have Docker privileges (typically membership in the `docker` group) +- A stack file (docker-compose YAML format) available in the repository or generated during the workflow +- For private container images: credentials for the container registry where the images are hosted + + ## Configuration options | GitHub Action Input | Environment Variable | Summary | Required | Default Value | @@ -61,6 +72,67 @@ repository UI, and used to surface much later as an opaque structural in a PEM key, and whitespace can be a legitimate part of a token. +## Optional Parameters + +### Registry Authentication + +Container registry authentication is skipped when either `username` or `password` is not provided. This is useful when deploying public images that do not require credentials. + +### `deploy_timeout` + +Specifies the number of seconds to wait for a deployment to converge. The default is 600 seconds (10 minutes). The action polls the remote Docker Swarm manager via SSH to check deployment status using the `docker-stack-wait` script. + +```yaml +- name: Deploy + uses: kitconcept/docker-stack-deploy@v1.5.0 + with: + deploy_timeout: "1200" + # ... other inputs +``` + +### `resolve_image` + +Controls whether the action queries the container registry to resolve image digests and supported platforms before deployment. Supported values are: + +- `always` (default): Always resolve image metadata +- `changed`: Only resolve for images that have changed since the last deployment +- `never`: Skip image resolution + +```yaml +- name: Deploy + uses: kitconcept/docker-stack-deploy@v1.5.0 + with: + resolve_image: "changed" + # ... other inputs +``` + +### `prune` + +When set to `1`, services that are not defined in the stack file are removed from the Swarm. The default is `0` (disabled). Use with caution on shared Swarms. + +```yaml +- name: Deploy + uses: kitconcept/docker-stack-deploy@v1.5.0 + with: + prune: "1" + # ... other inputs +``` + +### `scale_after` + +Scales a service to a specific number of replicas after a deployment has converged successfully. Useful when you want to adjust replica counts after initial deployment. + +```yaml +- name: Deploy + uses: kitconcept/docker-stack-deploy@v1.5.0 + with: + scale_after: "frontend=3 backend=2" + # ... other inputs +``` + +You can scale multiple services by separating them with spaces. + + ## Passing values into the stack file Your stack file can reference environment variables, and `docker stack deploy` From 0440996503f9e2b39ba8387691d81243104d2566 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Fri, 2 Oct 2026 10:12:49 -0300 Subject: [PATCH 4/5] Add towncrier fragment for README documentation fixes --- news/+readme-fixes.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/+readme-fixes.documentation diff --git a/news/+readme-fixes.documentation b/news/+readme-fixes.documentation new file mode 100644 index 0000000..d99d18a --- /dev/null +++ b/news/+readme-fixes.documentation @@ -0,0 +1 @@ +Improved README with clearer instructions, fixed broken examples, and added comprehensive documentation for optional parameters and prerequisites. From b1c9d6c694993c474f79a9680a0cd36d2a37bcee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Andrei?= Date: Fri, 2 Oct 2026 10:14:20 -0300 Subject: [PATCH 5/5] Correct the scale_after example and the dind version docker service scale needs the full Swarm service name, which is prefixed with the stack name, so the bare service names in the example would fail. The GitLab example now uses the same Docker major as the image (29). --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c69ba01..071006e 100644 --- a/README.md +++ b/README.md @@ -126,11 +126,13 @@ Scales a service to a specific number of replicas after a deployment has converg - name: Deploy uses: kitconcept/docker-stack-deploy@v1.5.0 with: - scale_after: "frontend=3 backend=2" + stack_name: "mystack" + scale_after: "mystack_frontend=3 mystack_backend=2" # ... other inputs ``` -You can scale multiple services by separating them with spaces. +The value is passed to `docker service scale`, so use the full Swarm service +name, `_`. Separate several services with spaces. ## Passing values into the stack file @@ -322,7 +324,7 @@ Then edit your `.gitlab-ci.yml` to include the `deploy` step: image: busybox:latest services: - - docker:26-dind + - docker:29-dind before_script: - docker info