Deploy and redeploy Docker Compose stacks in Portainer from Git

If you paste compose YAML into Portainer, the UI becomes the source of truth and drift appears the moment someone edits the file in Git. Using Portainer 2.x Stacks with the Repository build method keeps Git as the source of truth: Portainer fetches the compose definition from a repo at deploy time, and redeploys are triggered by changing the ref or calling a webhook.

Desired outcome

A Docker Compose application managed in Portainer CE/BE 2.x where the compose file lives in Git, deploys from a branch or tag, and can be redeployed safely by repointing the ref or via an external trigger. The stack detail page shows the repo URL and ref used, and the running workloads match the committed definition.

Prerequisites

A Portainer server already connected to a Docker environment, standalone or Swarm. The Portainer server process, not your browser, must reach the Git host over HTTP(S). That means DNS, egress and proxy rules for the container or host running Portainer.

A Git repository containing a valid compose file. For private repos you need a username and a personal access token or password accepted by the host. Use a read-only, narrowly scoped token.

Know the path to the compose file inside the repo and the target environment in Portainer. Compose behavior differs between standalone and Swarm targets, and directives such as build are handled differently per environment and Portainer version.

Create a stack from a repository

In Portainer open Stacks and start Add stack. Choose the Repository build method rather than Web editor. Set a stack name and select the target Docker environment.

Enter the repository URL, e.g. https://github.com/example-org/app-stack.git. Provide the ref, a branch or tag such as main, and the compose path relative to the repo root, e.g. docker-compose.yml or deploy/docker-compose.yml.

Add any required environment variables for the stack. Portainer stores Git credentials it is given; confirm storage and encryption behavior for your installed version and avoid long-lived broad tokens.

Deploy. Portainer clones the repo from the server side, reads the compose file at the specified ref and path, and creates the workloads. Do not edit the stack via the UI afterwards if you want Git to remain authoritative; UI edits are not written back to the repo.

Redeploy and trigger options

The stack detail page shows the repository URL and ref used for the current deployment. From there you can pull the repository and redeploy, typically with an option to re-pull images before recreating containers.

A per-stack webhook can be enabled. Portainer displays a webhook URL for the stack. An external CI job can trigger a redeploy by POSTing to that URL.

Example invocation from a machine with internet access:

curl -X POST https://portainer.example.com/api/webhooks/<webhook-id>

No authentication is required for the webhook URL itself. Treat the URL as a secret, do not commit or log it. Accidental or malicious calls will trigger a redeploy.

Scheduled automatic Git polling behavior varies by edition and version. Verify against the documentation for your installed version before relying on it.

Expected checks

After creation the stack appears in the Stacks list with its workloads reported as running. The stack detail page records the repository URL and reference used.

Container logs and a console are reachable from the Portainer UI for each service. After a commit to the repo and a manual redeploy or webhook trigger, the running image and compose definition should correspond to the new commit at the ref you deployed.

To verify reachability, confirm from the Portainer host that the repo can be cloned with the same credentials:

git ls-remote https://<user>:<token>@github.com/example-org/app-stack.git

Run this on the Portainer server container or host with permissions to execute git. Failure here indicates network or credential issues, not a Portainer bug.

Recovery and rollback

Portainer does not keep its own revision history of the compose definition. Git history is the rollback source of truth.

To roll back, edit the stack repository settings and repoint the ref to a previous branch, tag, or commit that contains a known good compose file, then redeploy. This recreates containers based on the older definition.

Deleting a stack removes the workloads it created. Named external volumes and resources created outside the stack are generally left in place.

Limitations

Exact UI labels, credential storage options, and edition feature splits have shifted across 2.x releases. Match the installed version shown in the Portainer UI to the corresponding docs before publishing exact menu names or toggle descriptions.

The Git repository must be reachable from the Portainer server process. Corporate proxies, DNS, or egress rules commonly cause deploy failures that appear as Portainer errors.

Compose support differs between Docker standalone and Swarm, and support for directives such as build has changed across versions. Test the specific compose file against the target environment type.