# docs/inputs.md

# Inputs

💡 Click on the **Input Name** for more [Details](#details).

| Input Name                  | Default Input Value | Short Description of Input |
| :------------------------------- | :---------------------------- | :---------------------------------------- |
| [name](#name) **\*** <CB />      | _Required_                    | Stack Name                                |
| [url](#url) **\*** <CB />        | _Required_                    | Portainer URL                             |
| [token](#token) **\*** <CB />    | _Required_                    | Portainer Token                           |
| [file](#file) <CB />             | `docker-compose.yaml`         | Compose File                              |
| [endpoint](#endpoint) <CB />     | `endpoints[0].Id`             | Portainer Endpoint                        |
| [ref](#ref) <CB />               | `current reference`           | Repository Ref                            |
| [repo](#repo) <CB />             | `current repository`          | Repository URL                            |
| [tlsskip](#tlsskip) <CB />       | `false`                       | Skip Repo TLS Verify                      |
| [prune](#prune) <CB />           | `true`                        | Prune Services                            |
| [pull](#pull) <CB />             | `true`                        | Pull Images                               |
| [type](#type) <CB />             | `repo`                        | Type [`repo`, `file`]                     |
| [standalone](#standalone) <CB /> | `false`                       | Deploy Standalone Stack                   |
| [env_data](#env_data) <CB />     | -                             | Dotenv JSON Data                          |
| [env_json](#env_data) <CB />     | **DEPRECATED**                | Use [env_data](#env_data)                 |
| [env_file](#env_file) <CB />     | -                             | Dotenv File Path                          |
| [merge_env](#merge_env) <CB />   | `false`                       | Merge Env Vars                            |
| [username](#username) <CB />     | -                             | Repository Username                       |
| [password](#password) <CB />     | -                             | Repository Password                       |
| [fs_path](#fs_path) **¹** <CB /> | -                             | Relative Path (BE)                        |
| [headers](#headers) <CB />       | `"{}"`                        | Custom Headers JSON                       |
| [summary](#summary) <CB />       | `true`                        | Add Summary to Job                        |

> **\* Required**  
> **¹ Business Edition**

For more details on inputs see the [Portainer CE API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ce/).

## Details

### name <CB /> <Badge type="warning" text="Requierd" />

Swarm sack name or Compose project name.

Example: `cool-stack`

### url <CB /> <Badge type="warning" text="Requierd" />

Portainer URL.

This is the base url to your Portainer instance.

Example: `https://portainer.example.com:9443`

### token <CB /> <Badge type="warning" text="Requierd" />

Portainer API token.

For Instructions to create an API token visit: https://docs.portainer.io/api/access

### file <CB />

The Docker compose file. This path is relative to your working directory.

If you check out your repository to the root, and the compose file is called `docker-compose.yaml`, and is in the `app` directory, set `file` to: `app/docker-compose.yaml`

Default: `docker-compose.yaml`

### endpoint <CB />

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.

Example: `1`

Default: `${endpoints[0]}`

### ref <CB />

This defaults to the reference that triggered the workflow.

If deploying from a different [repo](#repo) than the current one, you may want to specify the `ref` of that repository to deploy from.

Example: `refs/heads/master`

Default: <span v-pre>`${{ github.ref }}`</span>

### repo <CB />

This defaults to the repository running the action.

If you want to deploy a different repository, put the full http URL to that repository.

Note: you probably also want to specify the [ref](#ref) from that repository to use.

Example: `https://github.com/cssnr/portainer-stack-deploy-action`

Default: <span v-pre>`${{ github.server_url }}/${{ github.repository }}`</span>

### tlsskip <CB />

Skips SSL verification when cloning the Git repository.
Set to `true` to enable.

Default: `false`

### prune <CB />

Prune services that are no longer referenced (only available for Swarm stacks).
Set to `false` to disable.

Default: `true`

### pull <CB />

Pull latest image before deploy. Set to `false` to disable.

Default: `true`

### type <CB />

Type of Deployment. Supports either `repo` or `file`.

Default: `repo`

### standalone <CB />

Deploy a **compose** stack instead of _swarm_. Set to `true` to enable.

Default: `false`

### env_data <CB /> {#env_data}

Optional environment variables used when creating the stack.

These can be provided in JSON or YAML format and can be used with [env_file](#env_file).
Values in [env_file](#env_file) take precedence over these values.

::: details View JSON/YAML Input Examples

These examples are identical, just different ways of passing the input.

::: code-group

```yaml [YAML]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: |
      KEY: Value
      KEY_2: Value 2
```

```yaml [Multi-Line JSON]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: |
      {
        "KEY": "Value",
        "KEY_2": "Value 2"
      }
```

```yaml [Single Line JSON]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: '{"KEY": "Value", "KEY_2": "Value 2"}'
```

Note: Additional [inputs](../docs/inputs.md) are excluded for brevity.

:::

::: warning
Inputs are NOT secure unless using secrets or secure output (masked).
Using `env_data` on a public repository will otherwise expose this data in the actions' logs.
For an example of an action that produces secure out for use with `env_data` see the [hashicorp/vault-action example](../guides/examples.md#multi-step).
To securely pass unmasked values, use the [env_file](#env_file) option.
:::

### env_file <CB /> {#env_file}

Environment File in [dotenv](https://www.npmjs.com/package/dotenv) format, parsed using [dotenv](https://www.npmjs.com/package/dotenv).

This can be used with [env_data](#env_data). Values in this file take precedence over [env_data](#env_data).

::: details View Environment File Input Example

::: code-group

```dotenv [.env]
KEY="Value"
KEY_2="Value 2"
```

```yaml [.github/workflow.yaml]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_file: .env
```

Note: Additional [inputs](../docs/inputs.md) are excluded for brevity.
:::

### merge_env <CB /> {#merge_env}

Set this to `true` to merge the current environment variables from the existing stack
with any newly provided variables in the [env_data](#env_data) or [env_file](#env_file) inputs.

When not providing the [env_data](#env_data) or [env_file](#env_file) inputs the
current environment variables from the existing stack are always used.

When deploying a new stack, there are no current environment variables to merge, and this has no effect.

Default: `false`

### username <CB />

Username for private repository authentication when [type](#type) is set to `repo`.

This is **NOT** your Portainer username, see [token](#token) for Portainer authentication.

### password <CB />

Password for private repository authentication when [type](#type) is set to `repo`.

This is **NOT** your Portainer password, see [token](#token) for Portainer authentication.

### fs_path <CB /> <Badge type="tip" text="Business Edition" /> {#fs_path}

Relative Path Support for Portainer BE.
Set this to enable relative path volumes support for volume mappings in your compose file.

_For more info see the [Portainer Documentation - Relative Path Support](https://docs.portainer.io/advanced/relative-paths)._

### headers <CB />

Custom Headers in JSON or YAML format for services like Cloudflare Zero Trust.

The `headers` are parsed with `JSON.parse` or `yaml.load` and passed directly to axios.

```javascript
headers: { 'X-API-Key': token, ...JSON.parse(headers) }
```

::: details View Headers Input Example

::: code-group

```yaml [YAML]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: |
      CF-Access-Client-Id: ${{ secrets.CF_CLIENT_ID }}
      CF-Access-Client-Secret: ${{ secrets.CF_CLIENT_SECRET }}
```

```yaml [Multi-Line JSON]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: |
      {
        "CF-Access-Client-Id": "${{ secrets.CF_CLIENT_ID }}",
        "CF-Access-Client-Secret": "${{ secrets.CF_CLIENT_SECRET }}"
      }
```

```yaml [toJSON Output]
- uses: cssnr/portainer-stack-deploy-action@v1
  with:
    env_data: ${{ toJSON(steps.import-secrets.outputs) }}
```

Note: Additional [inputs](../docs/inputs.md) are excluded for brevity.

:::

### summary <CB />

Write a Summary for the job. To disable this set to `false`.

For more information see [Job Summary](../guides/features.md#job-summary).

Default: `true`

<style>
.inputs-page td {
    padding: 8px 12px !important;
    white-space: nowrap;
}
</style>

---

# docs/outputs.md

# Outputs

Details about the stack are output for use in additional steps.

| Input&nbsp;Name                  | Description |
| :------------------------------- | :---------- |
| [stackID](#stackID) <CB />       | Stack ID    |
| [swarmID](#swarmID) <CB />       | Swarm ID    |
| [endpointID](#endpointID) <CB /> | Endpoint ID |

### stackID <CB /> {#stackID}

This is the Portainer Stack ID used by portainer to identify the stack.

Example: `123`

### swarmID <CB /> {#swarmID}

This is the Portainer Swarm ID that the stack was deployed too.

Example: `wr8i8agdr05n6wsf1tkcnhwik`

### endpointID <CB /> {#endpointID}

This is the Portainer Endpoint ID the stack was deployed too.

If you did not specify an [endpoint](inputs.md#endpoint) input the action will
get the endpoints and use the first one (if multiple are returned).

Example: `1`

&nbsp;

::: tip
Please [let us know](../support.md) if you need more outputs.
:::

---

# guides/get-started.md

# Getting Started

<span class="search-keywords">Install and Setup Guide to Begin.</span>

To get started, create or update your [workflow file](#workflow) and review the [usage](#usage).

_You can also view the [features](features.md) and additional [examples](examples.md)._

## Workflow

Add the step to an existing workflow or create a new one.

_If creating a [new workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows), place it in the `.github/workflows` directory._

<!-- prettier-ignore-start -->

::: code-group
<<< @/snippets/guides/get-started/step.yaml {4,5 yaml} [Existing Workflow ~vscode-icons:folder-type-github~]
<<< @/snippets/guides/get-started/workflow.yaml {15,16 yaml} [New Workflow ~vscode-icons:folder-type-github~]
:::

<!-- prettier-ignore-end -->

**Make sure to update the highlighted lines and add your [secrets](#secrets).**

The only 3 required inputs are [token](../docs/inputs.md#token), [url](../docs/inputs.md#url), and [name](../docs/inputs.md#name).

Check out the [Rolling Tags](features.md#rolling-tags) for more tag options, however `@v1` is recommended.

<LatestVersion repo="cssnr/portainer-stack-deploy-action" />

<div class="tip custom-block" style="padding-top: 8px">

See the [Inputs Documentation](../docs/inputs.md) for additional options and **default values**.

</div>

## Usage

You only need to set the [name](../docs/inputs.md#name), [url](../docs/inputs.md#url), [token](../docs/inputs.md#token) and optionally the stack [file](../docs/inputs.md#file) to deploy a stack.

The compose [file](../docs/inputs.md#file) path is relative to your working directory.
If you check out your repository to the root and your compose file is in the `app` directory, set [file](../docs/inputs.md#file) to: `app/docker-compose.yaml`

You can provide environment variables from either a file or JSON/YAML.
If providing secrets via [env_data](../docs/inputs.md#env_data) they should come from secure input (masked).

<div class="tip custom-block" style="padding-top: 8px">

See the [Inputs Documentation](../docs/inputs.md) for more options and detailed usage.

</div>

## Secrets

You should store your credentials in [GitHub Actions Secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets).

You do not need to add all values as a secret. However, be aware that any inputs not added as a secret,
will be visible in the [GitHub Actions Logs](https://docs.github.com/en/actions/how-tos/monitor-workflows/use-workflow-run-logs).

Likewise, if you add your GitHub username as a secret,
these values will be replaced with `***`'s anywhere they appear in the logs, including repository names.

If working within an [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations)
you can create these secrets in the organization and make them available to all your repositories.
_This is why I use the [cssnr](https://github.com/cssnr) organization._

## Native Docker

If you don't use Portainer, you can deploy directly to a native [Docker](https://docs.docker.com/) host.

For this you should use: [cssnr/stack-deploy-action](https://github.com/cssnr/stack-deploy-action)

- https://github.com/marketplace/actions/docker-stack-deploy

For more details visit the website: https://docker-deploy.cssnr.com/

<!--@include: ./include/context-action.md-->

&nbsp;

::: info Request a Feature
If you need more options, please [open a feature request](https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/feature-requests)
:::

---

# guides/github-deploy.md

# Deploy from GitHub

Instructions for creating a Docker image, pushing it to GitHub Container Registry (GHCR), and deploying to Portainer with registry authentication.

[[toc]]

## Build and Push an Image

You can build a single image from a `Dockerfile`, or multiple images from a `docker-compose.yaml` file.

### Dockerfile

This example uses [docker/build-push-action](https://github.com/docker/build-push-action)

::: details docker-compose.yaml

This is only an example compose file.
**You should use your compose file.**

```yaml
version: '3.8'

services:
  alpine:
    image: alpine
    command: tail -f /dev/null
```

:::

::: details .github/workflow.yaml <Badge type="warning" text="WIP" />

<<< @/snippets/guides/github/build-push.yaml [yaml]

:::

### Compose Bake

This example uses [docker/bake-action](https://github.com/docker/bake-action)

This is how I build and deploy all my multi-image stacks to Portainer, from the `docker-compose.yaml` file.

::: details .github/workflow.yaml <Badge type="warning" text="WIP" />

<<< @/snippets/guides/github/bake.yaml [yaml]

:::

The full example can be found here: https://github.com/cssnr/django5-boiler/

_Note: the build and push actions are abstracted out into composite workflows for reusability.
However, this means you have to look at 3 files to see the full workflow._

## Configure Image Visibility

Newly published packages (images) are set to private visibility by default.
Unless you intend to share this image with others you can leave it as [Private](#private).
Otherwise, see instructions for changing visibility to [Public](#public)

### Private

You will need to configure portainer to pull the private image from GitHub.

See [Add Private GitHub Registry](#add-private-github-registry).

### Public <Badge type="warning" text="WIP" />

To change the image visibility to public, go to GitHub.

## Add Private GitHub Registry

First [Create a PAT](#create-pat) on GitHub then [Add the Registry](#add-registry) to Portainer.

### Create PAT <Badge type="warning" text="WIP" />

**On GitHub**, create a Personal Access Token (PAT).

### Add Registry

**On Portainer**, go to Registries and click `+ Add registry`.

Choose Custom registry and enter the following:

| Key            | Value      | Description                             |
| -------------- | ---------- | --------------------------------------- |
| Name           | `ghcr.io`  | Arbitrary name displayed in the UI      |
| Registry URL   | `ghcr.io`  | Actual URL to match when authenticating |
| Authentication | `True`     | Toggle on to set Username/Password      |
| Username       | `username` | GitHub Username (associated with PAT)   |
| Password       | `PAT`      | GitHub Personal Access Token (PAT)      |

Save your changes.

Now Portainer will use these credentials for any images whose url matches the configured `Registry URL`.

## Deploy to Portainer <Badge type="warning" text="WIP" />

This is the easiest part...

---

# support.md

# Support

[![Features](https://img.shields.io/badge/features-brightgreen?style=for-the-badge&logo=rocket&logoColor=white)](https://github.com/cssnr/portainer-stack-deploy-action/issues/new?template=1-feature.yaml)
[![Issues](https://img.shields.io/badge/issues-red?style=for-the-badge&logo=southwestairlines&logoColor=white)](https://github.com/cssnr/portainer-stack-deploy-action/issues)
[![Discussions](https://img.shields.io/badge/discussions-blue?style=for-the-badge&logo=theconversation)](https://github.com/cssnr/portainer-stack-deploy-action/discussions)
[![Discord](https://img.shields.io/badge/discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/wXy6m2X8wY)

If you run into any issues or want to see any new features, please let us know!

Contributing is as easy as telling us [what features or changes](https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/feature-requests) you want to see next…

### GitHub Discussions

If you have a question or need help with anything,
start a discussion in [General](https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/general)
or [Q&A](https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/q-a).

If you want to see a new feature, start a discussion in
the [Feature Requests](https://github.com/cssnr/portainer-stack-deploy-action/discussions/categories/feature-requests) section.

[![Start A Discussion](https://img.shields.io/badge/Start_A_Discussion-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/portainer-stack-deploy-action/discussions)

### GitHub Issues

If you run into any problems or find a bug, please [open an issue](https://github.com/cssnr/portainer-stack-deploy-action/issues).

**These reports are treated with the highest priority.**

[![Report an Issue](https://img.shields.io/badge/Report_an_Issue-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/portainer-stack-deploy-action/issues)

### Discord Chat

You can chat with us about anything [on discord](https://discord.gg/wXy6m2X8wY).

From here you can contact me directly, `Shane@111150265075298304`.

[![Chat on Discord](https://img.shields.io/badge/Chat_on_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/wXy6m2X8wY)

&nbsp;

[![Ko-Fi](./public/images/ko-fi.png)](https://ko-fi.com/cssnr)