README.md

Portainer Stack Deploy Action

Deploy or Update a Portainer Stack from a Repository or Compose File. Supports most features including specifying the repository, compose file, environment variables and much more...

This action is written from the ground up in VanillaJS and is not a fork/clone of existing actions.

• Inputs
• Outputs
• Examples
• Troubleshooting
• Support
• Contributing

Note

Please submit a Feature Request for new features or Open an Issue if you find any bugs.

Inputs

input	required	default	description
token	Yes	-	Portainer Token *
url	Yes	-	Portainer URL
name	Yes	-	Stack Name
file	No	docker-compose.yaml	Compose File
endpoint	No	endpoints[0].Id	Portainer Endpoint *
ref	No	current reference	Repository Ref *
repo	No	current repository	Repository URL *
tlsskip	No	false	Skip Repo TLS Verify
prune	No	true	Prune Services
pull	No	true	Pull Images
type	No	repo	Type [repo, file] *
standalone	No	false	Deploy Standalone Stack
env_json	No	-	Dotenv JSON Data *
env_file	No	-	Dotenv File Path *
username	No	-	Repository Username *
password	No	-	Repository Password *

token - To create a Portainer API token see: https://docs.portainer.io/api/access

endpoint - If endpoint is not provided the first endpoint returned by the API will be used. If you only have one endpoint, this will work as expected, otherwise, you should provide an endpoint.

ref - If you want to deploy a different ref than the one triggering the workflow. Useful if you are deploying from another repository. Example: refs/heads/master

repo - This defaults to the repository running the action. If you want to deploy a different repository put the full http URL to that repository here.

type - Type of Deployment. Currently, supports either repo or file.

env_json/env_file - Optional environment variables used when creating the stack. File should be in dotenv format and JSON should be an object. Example: {"KEY": "Value"}

username/password - Only set these if the repo is private and requires authentication. This is NOT the Portainer username/password, see token for Portainer authentication.

- name: 'Portainer Deploy'
  uses: cssnr/portainer-stack-deploy-action@v1
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name
      file: docker-compose.yaml

For more information on variables, see the Portainer API Documentation: https://app.swaggerhub.com/apis/portainer/portainer-ce/2.19.5

Outputs

output	description
stackID	Stack ID
swarmID	Swarm ID
endpointID	Endpoint ID

- name: 'Portainer Deploy'
  id: stack
  uses: cssnr/portainer-stack-deploy-action@v1
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name

- name: 'Echo Output'
  run: |
      echo 'stackID: ${{ steps.stack.outputs.stackID }}'
      echo 'swarmID: ${{ steps.stack.outputs.swarmID }}'
      echo 'endpointID: ${{ steps.stack.outputs.endpointID }}'

Examples

Deploying a repository other than the current repository:

- name: 'Portainer Deploy'
  uses: cssnr/portainer-stack-deploy-action@v1
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name
      file: docker-compose.yaml
      repo: https://github.com/user/some-other-repo
      ref: refs/heads/master

Deploy from compose file and not repository:

- name: 'Portainer Deploy'
  uses: cssnr/portainer-stack-deploy-action@v1
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name
      file: docker-compose.yaml
      type: file

Specify environment variables, may use json, or file, or a combination of both:

- name: 'Portainer Deploy'
  uses: cssnr/portainer-stack-deploy-action@v1
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name
      file: docker-compose.yaml
      type: file
      env_json: '{"KEY": "Value"}'
      env_file: .env

To include this in a general workflow but only run on release events use an if:

• if: ${{ github.event_name == 'release' }}

- name: 'Portainer Deploy'
  uses: cssnr/portainer-stack-deploy-action@v1
  if: ${{ github.event_name == 'release' }}
  with:
      token: ${{ secrets.PORTAINER_TOKEN }}
      url: https://portainer.example.com:9443
      name: stack-name
      file: docker-compose.yaml

This example builds a docker image using BuildX Bake, then pushes and deploys to Portainer.

name: 'Build'

on:
    workflow_dispatch:
    push:
        branches:
            - master

jobs:
    build:
        name: 'Build'
        runs-on: ubuntu-latest
        timeout-minutes: 15
        permissions:
            contents: read
            packages: write

        steps:
            - name: 'Checkout'
              uses: actions/checkout@v4

            - name: 'Docker Login'
              uses: docker/login-action@v2
              with:
                  registry: ghcr.io
                  username: ${{ vars.GHCR_USER }}
                  password: ${{ secrets.GHCR_PASS }}

            - name: 'Setup Buildx'
              uses: docker/setup-buildx-action@v2
              with:
                  platforms: linux/amd64,linux/arm64

            - name: 'Bake and Push'
              uses: docker/bake-action@v5
              with:
                  push: true
                  files: docker-compose-build.yaml

            - name: 'Portainer Deploy'
              uses: cssnr/portainer-stack-deploy-action@v1
              with:
                  token: ${{ secrets.PORTAINER_TOKEN }}
                  url: https://portainer.example.com
                  name: stack-name
                  file: docker-compose-swarm.yaml

This is a fairly simple action, for more details see src/index.js and src/portainer.js.

Troubleshooting

Some common errors you might see:

• No such image: ghcr.io/user/repo-name:tag

Make sure your package is not private. If you intend to use a private package, then:
Go to Portainer Registries: https://portainer.example.com/#!/registries/new
Choose Custom registry, set ghcr.io for Registry URL, enable authentication, and add your username/token.

• Error: Resource not accessible by integration

Only applies to build-push-action or bake-action type actions, not this action.
Go to your repository action settings: https://github.com/user/repo/settings/actions
Make sure Workflow permissions are set to Read and write permissions.

Support

For general help or to request a feature, see:

• Q&A Discussion: https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results, you can:

• Report an Issue: https://github.com/cssnr/portainer-stack-deploy-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

Contributing

Currently, the best way to contribute to this project is to star this project on GitHub.

Additionally, you can support other GitHub Actions I have published:

• VirusTotal Action
• Update Version Tags Action
• Update JSON Value Action
• Parse Issue Form Action
• Mirror Repository Action
• Portainer Stack Deploy
• Mozilla Addon Update Action

For a full list of current projects to support visit: https://cssnr.github.io/