Skip to content

docs: document chain-path and fullchain-path inputs/outputs (PR #7) #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
krakenhavoc wants to merge 1 commit into from
Closed

docs: document chain-path and fullchain-path inputs/outputs (PR #7) #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 44 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,9 @@ Issue, renew, or download TLS certificates from [KrakenKey](https://krakenkey.io
| `wait` | Wait for issuance/renewal to complete | No | `true` |
| `poll-interval` | Poll interval when waiting (Go duration, e.g., `15s`) | No | `15s` |
| `poll-timeout` | Maximum time to wait (Go duration, e.g., `10m`) | No | `10m` |
| `cert-path` | Path to save the certificate PEM | No | `./cert.pem` |
| `cert-path` | Path to save the leaf certificate PEM | No | `./cert.pem` |
| `chain-path` | Path to save the intermediate chain PEM | No | `./chain.pem` |
| `fullchain-path` | Path to save the full chain PEM (leaf + intermediates) | No | `./fullchain.pem` |
| `key-path` | Path to save the private key PEM (issue only) | No | `./key.pem` |
| `csr-path` | Path to save the CSR PEM (issue only) | No | `./csr.pem` |
| `cli-version` | `krakenkey-cli` version to use (e.g., `v0.1.0`, or `latest`) | No | `latest` |
Expand All @@ -54,27 +56,29 @@ Issue, renew, or download TLS certificates from [KrakenKey](https://krakenkey.io
| `fingerprint` | SHA-256 fingerprint |
| `key-type` | Key type used (e.g., `ECDSA`) |
| `key-size` | Key size (e.g., `256`, `2048`) |
| `cert-path` | Absolute path to the saved certificate PEM |
| `cert-path` | Absolute path to the saved leaf certificate PEM |
| `chain-path` | Absolute path to the saved intermediate chain PEM |
| `fullchain-path` | Absolute path to the saved full chain PEM (leaf + intermediates) |
| `key-path` | Absolute path to the saved private key PEM (issue only) |
| `csr-path` | Absolute path to the saved CSR PEM (issue only) |

## Commands

### `issue` (default)

Generates a CSR locally, submits it to the KrakenKey API, waits for issuance (~4 minutes), and saves the certificate + private key to the runner filesystem.
Generates a CSR locally, submits it to the KrakenKey API, waits for issuance (~4 minutes), and saves the certificate, intermediate chain, and full chain to the runner filesystem.

**Required inputs:** `api-key`, `domain`

### `renew`

Triggers renewal of an existing certificate by ID, waits for completion, and downloads the new certificate.
Triggers renewal of an existing certificate by ID, waits for completion, and downloads the new certificate along with its chain files.

**Required inputs:** `api-key`, `cert-id`

### `download`

Downloads an already-issued certificate by ID. No issuance, no waiting.
Downloads an already-issued certificate by ID. Saves the leaf cert, intermediate chain (`chain-path`), and full chain (`fullchain-path`). No issuance, no waiting.

**Required inputs:** `api-key`, `cert-id`

Expand Down Expand Up @@ -112,6 +116,27 @@ jobs:

</details>

<details>
<summary>Deploy with full chain (nginx, HAProxy)</summary>

```yaml
- name: Issue TLS certificate
id: cert
uses: krakenkey/cert-action@v1
with:
api-key: ${{ secrets.KRAKENKEY_API_KEY }}
domain: api.example.com

- name: Deploy fullchain + key
run: |
# Use fullchain.pem for nginx ssl_certificate directive
scp ${{ steps.cert.outputs.fullchain-path }} server:/etc/ssl/certs/fullchain.pem
scp ${{ steps.cert.outputs.key-path }} server:/etc/ssl/private/key.pem
ssh server 'systemctl reload nginx'
```

</details>

<details>
<summary>Multi-domain certificate with SANs</summary>

Expand Down Expand Up @@ -158,6 +183,8 @@ jobs:
command: download
cert-id: '42'
cert-path: ./cert.pem
chain-path: ./chain.pem
fullchain-path: ./fullchain.pem
```

</details>
Expand Down Expand Up @@ -237,6 +264,18 @@ jobs:

</details>

## Certificate Chain Files

Every `issue`, `renew`, and `download` operation produces three certificate files:

| File | Input | Content | Use case |
|------|-------|---------|----------|
| `cert-path` | `cert-path` | Leaf certificate only | Peer verification, inspection |
| `chain-path` | `chain-path` | Intermediate CA chain only | Stapling, manual chain assembly |
| `fullchain-path` | `fullchain-path` | Leaf + intermediates (concatenated) | nginx `ssl_certificate`, HAProxy, most servers |

Most web servers (nginx, Caddy, HAProxy) expect the **full chain** in the certificate file. Use `${{ steps.cert.outputs.fullchain-path }}` for these deployments.

## Security

- **API key masking** — The API key is masked with `::add-mask::` as the very first operation, ensuring it is redacted from all log output.
Expand Down
Loading