Skip to content

Commit 830d5fc

Browse files
claveryclavery
committed
docs(ci-cd): document staging mTLS deployments via GitHub Actions
Add a Staging Environments section to the CI/CD guide covering the two-factor mTLS pattern (separate webdav hostname + .p12 client cert) in both CLI flag and GitHub Actions form. Extend the setup action with webdav-server, certificate, certificate-passphrase, and selfsigned inputs so workflows can target staging without bespoke env wiring. Cross-link with the existing mTLS section in the configuration guide.
1 parent 4e8bf59 commit 830d5fc

5 files changed

Lines changed: 176 additions & 0 deletions

File tree

‎.changeset/staging-ci-cd-docs.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@salesforce/b2c-dx-docs': patch
3+
---
4+
5+
Document deploying to staging environments (two-factor mTLS) from CI/CD. The `setup` GitHub Action now accepts `webdav-server`, `certificate`, `certificate-passphrase`, and `selfsigned` inputs so workflows can target staging instances that require a separate WebDAV hostname and a client certificate. The CI/CD guide includes a full GitHub Actions example using a base64-encoded `.p12` secret.

‎actions/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,12 @@ All actions accept auth inputs directly or read from `SFCC_*` environment variab
100100
| `mrt-project` | `MRT_PROJECT` | MRT operations |
101101
| `mrt-environment` | `MRT_ENVIRONMENT` | MRT operations |
102102
| `account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager |
103+
| `webdav-server` | `SFCC_WEBDAV_SERVER` | Staging WebDAV (cert. hostname) |
104+
| `certificate` | `SFCC_CERTIFICATE` | Two-factor mTLS (PKCS12 path) |
105+
| `certificate-passphrase` | `SFCC_CERTIFICATE_PASSPHRASE` | Two-factor mTLS |
106+
| `selfsigned` | `SFCC_SELFSIGNED` | Allow self-signed server certs |
107+
108+
For staging environments that require a separate WebDAV hostname and a client certificate, see the [Staging Environments guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/ci-cd.html#staging-environments-two-factor-mtls) for the full pattern (decoding a base64-encoded `.p12` from a secret + wiring it through `setup`).
103109

104110
## Plugins
105111

‎actions/setup/action.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,18 @@ inputs:
4949
account-manager-host:
5050
description: 'Account Manager hostname → SFCC_ACCOUNT_MANAGER_HOST'
5151
required: false
52+
webdav-server:
53+
description: 'Separate WebDAV hostname (used for staging cert. hostnames) → SFCC_WEBDAV_SERVER'
54+
required: false
55+
certificate:
56+
description: 'Path to PKCS12 client certificate for two-factor (mTLS) auth → SFCC_CERTIFICATE'
57+
required: false
58+
certificate-passphrase:
59+
description: 'Passphrase for the PKCS12 client certificate → SFCC_CERTIFICATE_PASSPHRASE'
60+
required: false
61+
selfsigned:
62+
description: 'Allow self-signed server certificates (true/false) → SFCC_SELFSIGNED'
63+
required: false
5264
log-level:
5365
description: 'CLI log level (trace, debug, info, warn, error, silent) → SFCC_LOG_LEVEL'
5466
required: false
@@ -127,6 +139,18 @@ runs:
127139
if [ -n "${{ inputs.account-manager-host }}" ]; then
128140
echo "SFCC_ACCOUNT_MANAGER_HOST=${{ inputs.account-manager-host }}" >> "$GITHUB_ENV"
129141
fi
142+
if [ -n "${{ inputs.webdav-server }}" ]; then
143+
echo "SFCC_WEBDAV_SERVER=${{ inputs.webdav-server }}" >> "$GITHUB_ENV"
144+
fi
145+
if [ -n "${{ inputs.certificate }}" ]; then
146+
echo "SFCC_CERTIFICATE=${{ inputs.certificate }}" >> "$GITHUB_ENV"
147+
fi
148+
if [ -n "${{ inputs.certificate-passphrase }}" ]; then
149+
echo "SFCC_CERTIFICATE_PASSPHRASE=${{ inputs.certificate-passphrase }}" >> "$GITHUB_ENV"
150+
fi
151+
if [ -n "${{ inputs.selfsigned }}" ]; then
152+
echo "SFCC_SELFSIGNED=${{ inputs.selfsigned }}" >> "$GITHUB_ENV"
153+
fi
130154
if [ -n "${{ inputs.log-level }}" ]; then
131155
echo "SFCC_LOG_LEVEL=${{ inputs.log-level }}" >> "$GITHUB_ENV"
132156
fi

‎docs/guide/ci-cd.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,30 @@ Installs the CLI and writes credentials to environment variables. Use this when
125125

126126
Plugins are installed after the CLI and cached across runs. Each line is an npm package name or GitHub `owner/repo`.
127127

128+
The setup action accepts the following inputs (each maps to the corresponding `SFCC_*` environment variable):
129+
130+
| Input | Environment Variable |
131+
|-------|---------------------|
132+
| `client-id` | `SFCC_CLIENT_ID` |
133+
| `client-secret` | `SFCC_CLIENT_SECRET` |
134+
| `server` | `SFCC_SERVER` |
135+
| `code-version` | `SFCC_CODE_VERSION` |
136+
| `username` | `SFCC_USERNAME` |
137+
| `password` | `SFCC_PASSWORD` |
138+
| `short-code` | `SFCC_SHORTCODE` |
139+
| `tenant-id` | `SFCC_TENANT_ID` |
140+
| `account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` |
141+
| `webdav-server` | `SFCC_WEBDAV_SERVER` |
142+
| `certificate` | `SFCC_CERTIFICATE` |
143+
| `certificate-passphrase` | `SFCC_CERTIFICATE_PASSPHRASE` |
144+
| `selfsigned` | `SFCC_SELFSIGNED` |
145+
| `mrt-api-key` | `MRT_API_KEY` |
146+
| `mrt-project` | `MRT_PROJECT` |
147+
| `mrt-environment` | `MRT_ENVIRONMENT` |
148+
| `log-level` | `SFCC_LOG_LEVEL` |
149+
150+
The `webdav-server`, `certificate`, `certificate-passphrase`, and `selfsigned` inputs are only needed for staging environments that require a separate WebDAV hostname and a client certificate (mTLS). See [Staging Environments (Two-Factor mTLS)](#staging-environments-two-factor-mtls).
151+
128152
### Run
129153

130154
```
@@ -277,6 +301,117 @@ Upload files via WebDAV.
277301
| `remote-path` | *(required)* | Remote destination path |
278302
| `root` | `IMPEX` | WebDAV root (IMPEX, TEMP, CARTRIDGES, etc.) |
279303

304+
## Staging Environments (Two-Factor mTLS)
305+
306+
Internal staging instances typically require:
307+
308+
- A separate WebDAV hostname (often a `cert.*` variant of the main hostname)
309+
- A PKCS12 (`.p12`) client certificate with passphrase for mutual TLS
310+
- Permission to accept self-signed server certificates
311+
312+
See [Two-Factor Authentication (mTLS)](/guide/configuration#two-factor-authentication-mtls) for the underlying configuration model.
313+
314+
### CLI Flags
315+
316+
The same options that go in `dw.json` are available as CLI flags. For local use against a staging instance:
317+
318+
```bash
319+
b2c code deploy \
320+
--server staging-internal-ccdemo.demandware.net \
321+
--webdav-server cert.staging.internal.ccdemo.demandware.net \
322+
--certificate /path/to/STG-2FA-ccdemo/deploy.p12 \
323+
--passphrase 'your-cert-passphrase' \
324+
--selfsigned \
325+
--client-id "$SFCC_CLIENT_ID" \
326+
--client-secret "$SFCC_CLIENT_SECRET"
327+
```
328+
329+
| Flag | dw.json Field | Environment Variable |
330+
|------|---------------|---------------------|
331+
| `--server` | `hostname` | `SFCC_SERVER` |
332+
| `--webdav-server` | `webdav-hostname` | `SFCC_WEBDAV_SERVER` |
333+
| `--certificate` | `certificate` | `SFCC_CERTIFICATE` |
334+
| `--passphrase` | `certificate-passphrase` | `SFCC_CERTIFICATE_PASSPHRASE` |
335+
| `--selfsigned` | `self-signed` | `SFCC_SELFSIGNED` |
336+
337+
### GitHub Actions
338+
339+
Staging mTLS works with the standard actions — the `setup` action accepts `webdav-server`, `certificate`, `certificate-passphrase`, and `selfsigned` inputs alongside the usual auth inputs.
340+
341+
Because the `.p12` is a binary file, store it as a base64-encoded GitHub secret and decode it to disk in a workflow step before calling `setup`. The `certificate` input then points at the decoded path.
342+
343+
**Recommended secrets/variables for staging:**
344+
345+
| Secret | Description |
346+
|--------|-------------|
347+
| `SFCC_STAGING_CERTIFICATE_P12_BASE64` | Base64-encoded `.p12` client certificate |
348+
| `SFCC_STAGING_CERTIFICATE_PASSPHRASE` | Passphrase for the `.p12` |
349+
| `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` | OAuth credentials |
350+
351+
| Variable | Description |
352+
|----------|-------------|
353+
| `SFCC_STAGING_SERVER` | e.g. `staging-internal-ccdemo.demandware.net` |
354+
| `SFCC_STAGING_WEBDAV_SERVER` | e.g. `cert.staging.internal.ccdemo.demandware.net` |
355+
356+
To create the base64 secret locally:
357+
358+
```bash
359+
base64 -i deploy.p12 | pbcopy # macOS
360+
# or
361+
base64 -w0 deploy.p12 # Linux
362+
```
363+
364+
Then paste the value into a GitHub repository secret.
365+
366+
**Workflow example:**
367+
368+
```yaml
369+
name: Deploy to Staging
370+
371+
on:
372+
workflow_dispatch:
373+
374+
jobs:
375+
deploy:
376+
runs-on: ubuntu-latest
377+
steps:
378+
- uses: actions/checkout@v4
379+
380+
# Decode the .p12 to a file inside the runner workspace
381+
- name: Decode staging client certificate
382+
run: |
383+
echo "${{ secrets.SFCC_STAGING_CERTIFICATE_P12_BASE64 }}" \
384+
| base64 --decode > "$RUNNER_TEMP/staging-deploy.p12"
385+
chmod 600 "$RUNNER_TEMP/staging-deploy.p12"
386+
387+
- uses: SalesforceCommerceCloud/b2c-developer-tooling/actions/setup@v1
388+
with:
389+
client-id: ${{ secrets.SFCC_CLIENT_ID }}
390+
client-secret: ${{ secrets.SFCC_CLIENT_SECRET }}
391+
server: ${{ vars.SFCC_STAGING_SERVER }}
392+
webdav-server: ${{ vars.SFCC_STAGING_WEBDAV_SERVER }}
393+
certificate: ${{ runner.temp }}/staging-deploy.p12
394+
certificate-passphrase: ${{ secrets.SFCC_STAGING_CERTIFICATE_PASSPHRASE }}
395+
selfsigned: 'true'
396+
397+
- run: npm ci && npm run build
398+
399+
- uses: SalesforceCommerceCloud/b2c-developer-tooling/actions/code-deploy@v1
400+
with:
401+
code-version: staging-${{ github.run_number }}
402+
activate: true
403+
```
404+
405+
Once the `setup` step writes `SFCC_CERTIFICATE`, `SFCC_WEBDAV_SERVER`, etc. to `$GITHUB_ENV`, every subsequent action picks them up automatically — no need to repeat them on `code-deploy`, `data-import`, `job-run`, or `webdav-upload`.
406+
407+
::: tip Multiple Environments in One Workflow
408+
If a single workflow targets both a normal sandbox and a staging instance, run `setup` again before each phase with the appropriate inputs. The second `setup` overwrites the relevant env vars for subsequent steps.
409+
:::
410+
411+
::: warning Cleanup
412+
The decoded `.p12` lives only inside the runner's ephemeral workspace and is destroyed when the job ends. Never commit the file or write it outside `$RUNNER_TEMP` / the workspace.
413+
:::
414+
280415
## Patterns
281416

282417
### Data Import Pipeline

‎docs/guide/configuration.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,12 @@ For instances that require client certificate authentication:
290290

291291
The certificate must be in PKCS12 format (`.p12` or `.pfx`). The `self-signed` option is often needed for staging environments with internal certificates.
292292

293+
The same fields are available as CLI flags (`--webdav-server`, `--certificate`, `--passphrase`, `--selfsigned`) and as environment variables (`SFCC_WEBDAV_SERVER`, `SFCC_CERTIFICATE`, `SFCC_CERTIFICATE_PASSPHRASE`, `SFCC_SELFSIGNED`).
294+
295+
::: tip Running staging deploys in CI/CD
296+
For GitHub Actions workflows that target staging — including how to handle the `.p12` certificate as a base64-encoded secret — see [Staging Environments (Two-Factor mTLS)](/guide/ci-cd#staging-environments-two-factor-mtls).
297+
:::
298+
293299
::: tip MRT Configuration
294300
MRT API key can also be loaded from `~/.mobify`. See [MRT API Key](#mrt-api-key) below.
295301
:::

0 commit comments

Comments
 (0)