diff --git a/docs/docs/inputs.md b/docs/docs/inputs.md index d59af46..d8f9bdc 100644 --- a/docs/docs/inputs.md +++ b/docs/docs/inputs.md @@ -9,9 +9,9 @@ pageClass: inputs-page | Input Name | Default Input Value | Short Description of Input | | :------------------------------- | :---------------------------- | :---------------------------------------- | -| [name](#name) **\*** | - | Stack Name | -| [url](#url) **\*** | - | Portainer URL | -| [token](#token) **\*** | - | Portainer Token | +| [name](#name) **\*** | _Required_ | Stack Name | +| [url](#url) **\*** | _Required_ | Portainer URL | +| [token](#token) **\*** | _Required_ | Portainer Token | | [file](#file) | `docker-compose.yaml` | Compose File | | [endpoint](#endpoint) | `endpoints[0].Id` | Portainer Endpoint | | [ref](#ref) | `current reference` | Repository Ref | @@ -21,13 +21,14 @@ pageClass: inputs-page | [pull](#pull) | `true` | Pull Images | | [type](#type) | `repo` | Type [`repo`, `file`] | | [standalone](#standalone) | `false` | Deploy Standalone Stack | -| [env_json](#env_json) | - | Dotenv JSON Data | +| [env_data](#env_data) | - | Dotenv JSON Data | +| [env_json](#env_data) | **DEPRECATED** | Use [env_data](#env_data) | | [env_file](#env_file) | - | Dotenv File Path | | [merge_env](#merge_env) | `false` | Merge Env Vars | | [username](#username) | - | Repository Username | | [password](#password) | - | Repository Password | -| [headers](#headers) | `"{}"` | Custom Headers JSON | | [fs_path](#fs_path) **ยน** | - | Relative Path (BE) | +| [headers](#headers) | `"{}"` | Custom Headers JSON | | [summary](#summary) | `true` | Add Summary to Job | > **\* Required** @@ -78,7 +79,7 @@ Default: `${endpoints[0]}` This defaults to the reference that triggered the workflow. -If deploying from a different repository than the current one, you may want to specify the `ref` of that repository to deploy from. +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` @@ -90,6 +91,8 @@ 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: `${{ github.server_url }}/${{ github.repository }}` @@ -122,28 +125,35 @@ Default: `repo` ### standalone -Deploy a **compose** stack instead of _swarm_. -Set to `true` to enable. +Deploy a **compose** stack instead of _swarm_. Set to `true` to enable. Default: `false` -### env_json {#env_json} +### env_data {#env_data} Optional environment variables used when creating the stack. -File should be in dotenv format and JSON should be an object. Example: {"KEY": "Value"} -This can be used with [env_file](#env_file). Values in [env_file](#env_file) take precedence over these values. +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 Input Examples +::: 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_json: | + env_data: | { "KEY": "Value", "KEY_2": "Value 2" @@ -153,7 +163,7 @@ These examples are identical, just different ways of passing the input. ```yaml [Single Line JSON] - uses: cssnr/portainer-stack-deploy-action@v1 with: - env_json: '{"KEY": "Value", "KEY_2": "Value 2"}' + env_data: '{"KEY": "Value", "KEY_2": "Value 2"}' ``` Note: Additional [inputs](../docs/inputs.md) are excluded for brevity. @@ -162,8 +172,8 @@ Note: Additional [inputs](../docs/inputs.md) are excluded for brevity. ::: warning Inputs are NOT secure unless using secrets or secure output (masked). -Using `env_json` 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_json` see the [hashicorp/vault-action example](../guides/examples.md#multi-step). +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. ::: @@ -171,7 +181,7 @@ To securely pass unmasked values, use the [env_file](#env_file) option. 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_json](#env_json). Values in this file take precedence over [env_json](#env_json). +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 @@ -194,9 +204,9 @@ Note: Additional [inputs](../docs/inputs.md) are excluded for brevity. ### merge_env {#merge_env} Set this to `true` to merge the current environment variables from the existing stack -with any newly provided variables in the [env_json](#env_json) or [env_file](#env_file) inputs. +with any newly provided variables in the [env_data](#env_data) or [env_file](#env_file) inputs. -When not providing the [env_json](#env_json) or [env_file](#env_file) inputs the +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. @@ -215,11 +225,18 @@ Password for private repository authentication when [type](#type) is set to `rep This is **NOT** your Portainer password, see [token](#token) for Portainer authentication. +### fs_path {#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 -Custom Headers in **JSON** format for services like Cloudflare Zero Trust. +Custom Headers in JSON or YAML format for services like Cloudflare Zero Trust. -The `headers` are parsed with JSON.parse and passed directly to axios: +The `headers` are parsed with `JSON.parse` or `yaml.load` and passed directly to axios. ```javascript headers: { 'X-API-Key': token, ...JSON.parse(headers) } @@ -227,29 +244,36 @@ headers: { 'X-API-Key': token, ...JSON.parse(headers) } ::: details View Headers Input Example -```yaml +::: code-group + +```yaml [YAML] - uses: cssnr/portainer-stack-deploy-action@v1 with: - headers: | + 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. ::: -Default: `"{}"` - -### fs_path {#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)._ - ### summary Write a Summary for the job. To disable this set to `false`. diff --git a/docs/guides/features.md b/docs/guides/features.md index 88a1a4f..51e4afb 100644 --- a/docs/guides/features.md +++ b/docs/guides/features.md @@ -7,7 +7,7 @@ and [Business Enterprise Edition](https://www.portainer.io/solutions/portainer-f - Deploy or re-deploy an existing stack otherwise create a new stack. - Deploy from a repository or a compose file, see [type](../docs/inputs.md#type). - Deploy from a different [repo](../docs/inputs.md#repo) than the current one. -- Provide environment variables in [JSON](../docs/inputs.md#env_json) or [file](../docs/inputs.md#env_file) format. +- Provide environment variables in [JSON/YAML](../docs/inputs.md#env_data) or [file](../docs/inputs.md#env_file) format. - Automatically parse [Endpoint ID](../docs/inputs.md#endpoint) if only one endpoint. - Supports Docker Swarm and Docker [Standalone](../docs/inputs.md#standalone). - Supports custom [headers](../docs/inputs#headers) for services like Cloudflare Zero Trust. diff --git a/docs/guides/get-started.md b/docs/guides/get-started.md index 4845844..38f14e3 100644 --- a/docs/guides/get-started.md +++ b/docs/guides/get-started.md @@ -44,8 +44,8 @@ You only need to set the [name](../docs/inputs.md#name), [url](../docs/inputs.md 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. -If providing secrets via [env_json](../docs/inputs.md#env_json) they should come from secure input (masked). +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).
diff --git a/docs/snippets/examples/multi/tojson.yaml b/docs/snippets/examples/multi/tojson.yaml index 10c7952..25ebbfe 100644 --- a/docs/snippets/examples/multi/tojson.yaml +++ b/docs/snippets/examples/multi/tojson.yaml @@ -17,4 +17,4 @@ file: "docker-compose.yaml" url: ${{ secrets.PORTAINER_URL }} token: ${{ secrets.PORTAINER_TOKEN }} - env_json: ${{ toJSON(steps.import-secrets.outputs) }} + env_data: ${{ toJSON(steps.import-secrets.outputs) }} diff --git a/docs/snippets/examples/steps/env.yaml b/docs/snippets/examples/steps/env.yaml index 7d0ca14..32e0265 100644 --- a/docs/snippets/examples/steps/env.yaml +++ b/docs/snippets/examples/steps/env.yaml @@ -5,5 +5,5 @@ file: "docker-compose.yaml" url: ${{ secrets.PORTAINER_URL }} token: ${{ secrets.PORTAINER_TOKEN }} - env_json: '{"KEY": "Value"}' + env_data: '{"KEY": "Value"}' env_file: .env diff --git a/docs/snippets/examples/steps/json.yaml b/docs/snippets/examples/steps/json.yaml index 369cb65..a5cdb09 100644 --- a/docs/snippets/examples/steps/json.yaml +++ b/docs/snippets/examples/steps/json.yaml @@ -5,7 +5,7 @@ file: "docker-compose.yaml" url: ${{ secrets.PORTAINER_URL }} token: ${{ secrets.PORTAINER_TOKEN }} - env_json: | + env_data: | { "APP_PRIVATE_KEY": "${{ secrets.APP_PRIVATE_KEY }}", "VERSION": "${{ inputs.VERSION }}" diff --git a/docs/snippets/examples/steps/merge-env.yaml b/docs/snippets/examples/steps/merge-env.yaml index 5cf380e..e831a6c 100644 --- a/docs/snippets/examples/steps/merge-env.yaml +++ b/docs/snippets/examples/steps/merge-env.yaml @@ -5,5 +5,5 @@ file: "docker-compose.yaml" url: ${{ secrets.PORTAINER_URL }} token: ${{ secrets.PORTAINER_TOKEN }} - env_json: '{"KEY": "Value"}' + env_data: '{"KEY": "Value"}' merge_env: true diff --git a/docs/snippets/examples/workflows/full.yaml b/docs/snippets/examples/workflows/full.yaml index 01cc487..dd5d6b6 100644 --- a/docs/snippets/examples/workflows/full.yaml +++ b/docs/snippets/examples/workflows/full.yaml @@ -103,7 +103,7 @@ jobs: name: ${{ env.stack-name }} username: ${{ vars.GHCR_USER }} password: ${{ secrets.GHCR_PASS }} - env_json: | + env_data: | { "VERSION": "$${{ github.ref_name }}", "STACK_NAME": "${{ env.stack-name }}", diff --git a/docs/snippets/examples/workflows/workflow-run.yaml b/docs/snippets/examples/workflows/workflow-run.yaml index a60b086..b57a05b 100644 --- a/docs/snippets/examples/workflows/workflow-run.yaml +++ b/docs/snippets/examples/workflows/workflow-run.yaml @@ -45,7 +45,7 @@ jobs: name: ${{ env.stack-name }} username: ${{ vars.GHCR_USER }} password: ${{ secrets.GHCR_PASS }} - env_json: | + env_data: | { "VERSION": "${{ env.version == 'master' && 'latest' || env.version }}", "STACK_NAME": "${{ env.stack-name }}",