From c0890828550a9195d9eb232bbddda49a84ca4c48 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Wed, 27 May 2026 13:30:09 -0600 Subject: [PATCH 1/5] DOCS-863: clarify GitHub Action debug and TLS guidance --- .../plugins-overview/github-action.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/Integrations & Plugins/plugins-overview/github-action.md b/docs/Integrations & Plugins/plugins-overview/github-action.md index 412a5aeb9..443b86fee 100644 --- a/docs/Integrations & Plugins/plugins-overview/github-action.md +++ b/docs/Integrations & Plugins/plugins-overview/github-action.md @@ -141,6 +141,8 @@ This is only part of the `YAML` action. More complete examples are given in the key: "imp" ``` +Use `ca-certificate` when the workflow connects to a Gateway over TLS and the GitHub runner does not already trust the certificate chain. The runner must trust the Gateway certificate before the action can start authentication. Store the PEM-encoded CA certificate in a GitHub secret such as `AKEYLESS_CA_CERTIFICATE`, then pass that secret to `ca-certificate`. + > ⚠️ **Warning:** > > For JWT authentication, it is required to add appropriate [Sub-Claims](https://docs.akeyless.io/docs/sub-claims) based on the [claims available in the JWT](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) to prevent access by unauthorized users. @@ -166,6 +168,17 @@ For example: `repository=octo-org/octo-repo` where `octo-org = {GitHub Account}` The workflow examples use placeholder values. Replace them with your own Akeyless paths, authentication values, and cloud settings before running in production. +### Debug Logging + +Set `ACTIONS_STEP_DEBUG=true` in the workflow environment when you need step-level GitHub Actions debug logs while troubleshooting the Akeyless action. Add `ACTIONS_RUNNER_DEBUG=true` when you also need runner-level diagnostic output. + +```yaml +steps: + - name: Enable GitHub Actions step debug logging + run: | + echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV +``` + > ℹ️ **Note (Zero-Knowledge Encryption):** > > If you are working with your own Akeyless Gateway, set the parameter `api-url` to point your Gateway Rest API endpoint, for example, `https://Your_GW_URL:8000/api/v2` (or using your gateway URL at port `8081`). From 3a8c71d9a396f1417f9db22855c5587573e15c20 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Wed, 27 May 2026 13:33:04 -0600 Subject: [PATCH 2/5] DOCS-863: improve GitHub Action page structure --- .../plugins-overview/github-action.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/Integrations & Plugins/plugins-overview/github-action.md b/docs/Integrations & Plugins/plugins-overview/github-action.md index 443b86fee..11d500905 100644 --- a/docs/Integrations & Plugins/plugins-overview/github-action.md +++ b/docs/Integrations & Plugins/plugins-overview/github-action.md @@ -37,6 +37,19 @@ Configure a [self-hosted-runner](https://docs.github.com/en/actions/hosting-your * Follow the instructions in the **Download** section to prepare a directory for the GitHub runner, and then download the runner. * Follow the instructions in the **Configure** section to configure the runner to connect to GitHub with a token GitHub generates for the runner. +### Runner Trust and Debugging + +When the workflow connects to an Akeyless Gateway over TLS, the GitHub runner must trust the Gateway certificate chain before the action can start authentication. If the runner does not already trust that chain, store the PEM-encoded CA certificate in a GitHub secret such as `AKEYLESS_CA_CERTIFICATE` and pass it through the action's `ca-certificate` input. + +For troubleshooting, set `ACTIONS_STEP_DEBUG=true` to enable step-level GitHub Actions debug logs. Add `ACTIONS_RUNNER_DEBUG=true` when you also need runner-level diagnostic output. + +```yaml +steps: + - name: Enable GitHub Actions step debug logging + run: | + echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV +``` + ## Authentication This Action plugin supports the following Authentication Methods: @@ -50,7 +63,7 @@ This Action plugin supports the following Authentication Methods: * [Access Key](https://docs.akeyless.io/docs/auth-with-api-key) * [Certificate](https://docs.akeyless.io/docs/auth-with-certificate) -### GitHub Repository Variable +### GitHub Variables and Secrets You can store the `Access ID` as a GitHub variable inside the repository to use in your workflow. @@ -168,17 +181,6 @@ For example: `repository=octo-org/octo-repo` where `octo-org = {GitHub Account}` The workflow examples use placeholder values. Replace them with your own Akeyless paths, authentication values, and cloud settings before running in production. -### Debug Logging - -Set `ACTIONS_STEP_DEBUG=true` in the workflow environment when you need step-level GitHub Actions debug logs while troubleshooting the Akeyless action. Add `ACTIONS_RUNNER_DEBUG=true` when you also need runner-level diagnostic output. - -```yaml -steps: - - name: Enable GitHub Actions step debug logging - run: | - echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV -``` - > ℹ️ **Note (Zero-Knowledge Encryption):** > > If you are working with your own Akeyless Gateway, set the parameter `api-url` to point your Gateway Rest API endpoint, for example, `https://Your_GW_URL:8000/api/v2` (or using your gateway URL at port `8081`). From 94827553a8434b7e97d3cbb22670ebe63b92a94f Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Wed, 27 May 2026 13:35:33 -0600 Subject: [PATCH 3/5] DOCS-863: align debug guidance with action source --- .../plugins-overview/github-action.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/Integrations & Plugins/plugins-overview/github-action.md b/docs/Integrations & Plugins/plugins-overview/github-action.md index 11d500905..d812b61d2 100644 --- a/docs/Integrations & Plugins/plugins-overview/github-action.md +++ b/docs/Integrations & Plugins/plugins-overview/github-action.md @@ -41,13 +41,18 @@ Configure a [self-hosted-runner](https://docs.github.com/en/actions/hosting-your When the workflow connects to an Akeyless Gateway over TLS, the GitHub runner must trust the Gateway certificate chain before the action can start authentication. If the runner does not already trust that chain, store the PEM-encoded CA certificate in a GitHub secret such as `AKEYLESS_CA_CERTIFICATE` and pass it through the action's `ca-certificate` input. -For troubleshooting, set `ACTIONS_STEP_DEBUG=true` to enable step-level GitHub Actions debug logs. Add `ACTIONS_RUNNER_DEBUG=true` when you also need runner-level diagnostic output. +The action emits debug messages through GitHub Actions debug commands. For more detailed action logs, set `ACTIONS_RUNNER_DEBUG=true`. If you also want GitHub Actions step debug logging for the workflow step, set `ACTIONS_STEP_DEBUG=true`. + +> ⚠️ **Important:** +> +> Setting `ACTIONS_RUNNER_DEBUG=true` can expose sensitive information in error logs. Use it with caution. ```yaml steps: - name: Enable GitHub Actions step debug logging run: | echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV + echo "ACTIONS_RUNNER_DEBUG=true" >> $GITHUB_ENV ``` ## Authentication From eb998108d93b32efa05565f3aca93790cb6240ca Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Wed, 27 May 2026 13:37:12 -0600 Subject: [PATCH 4/5] DOCS-863: add Gateway TLS example --- .../plugins-overview/github-action.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/Integrations & Plugins/plugins-overview/github-action.md b/docs/Integrations & Plugins/plugins-overview/github-action.md index d812b61d2..e705a2076 100644 --- a/docs/Integrations & Plugins/plugins-overview/github-action.md +++ b/docs/Integrations & Plugins/plugins-overview/github-action.md @@ -41,6 +41,23 @@ Configure a [self-hosted-runner](https://docs.github.com/en/actions/hosting-your When the workflow connects to an Akeyless Gateway over TLS, the GitHub runner must trust the Gateway certificate chain before the action can start authentication. If the runner does not already trust that chain, store the PEM-encoded CA certificate in a GitHub secret such as `AKEYLESS_CA_CERTIFICATE` and pass it through the action's `ca-certificate` input. +For example, when the workflow uses a TLS-enabled Gateway endpoint, pass both the Gateway API URL and the CA certificate: + +```yaml +steps: + - name: Fetch a secret through a TLS-enabled Gateway + uses: akeyless-community/akeyless-github-action@v1.1.5 + with: + access-id: ${{ vars.AKEYLESS_ACCESS_ID }} + access-type: universal_identity + uid_token: ${{ secrets.AKEYLESS_UID_TOKEN }} + api-url: https://your-gateway.example.com:8000/api/v2 + ca-certificate: ${{ secrets.AKEYLESS_CA_CERTIFICATE }} + static-secrets: | + - name: "/path/to/secret" + output-name: "my_secret" +``` + The action emits debug messages through GitHub Actions debug commands. For more detailed action logs, set `ACTIONS_RUNNER_DEBUG=true`. If you also want GitHub Actions step debug logging for the workflow step, set `ACTIONS_STEP_DEBUG=true`. > ⚠️ **Important:** From 46ac82a714fd5d52ef2bc9ddfd74bb7afbb74d0a Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Wed, 27 May 2026 13:38:17 -0600 Subject: [PATCH 5/5] DOCS-863: deduplicate Gateway TLS guidance --- docs/Integrations & Plugins/plugins-overview/github-action.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Integrations & Plugins/plugins-overview/github-action.md b/docs/Integrations & Plugins/plugins-overview/github-action.md index e705a2076..14d268149 100644 --- a/docs/Integrations & Plugins/plugins-overview/github-action.md +++ b/docs/Integrations & Plugins/plugins-overview/github-action.md @@ -176,7 +176,7 @@ This is only part of the `YAML` action. More complete examples are given in the key: "imp" ``` -Use `ca-certificate` when the workflow connects to a Gateway over TLS and the GitHub runner does not already trust the certificate chain. The runner must trust the Gateway certificate before the action can start authentication. Store the PEM-encoded CA certificate in a GitHub secret such as `AKEYLESS_CA_CERTIFICATE`, then pass that secret to `ca-certificate`. +For Gateway TLS trust requirements and a complete example, see [Runner Trust and Debugging](https://docs.akeyless.io/docs/github-action#runner-trust-and-debugging). > ⚠️ **Warning:** >