docs: document az-sync action and nginx.org-make-aws workflow

README.md

@@ -140,3 +140,116 @@ on:
     paths:
       - docsDirectory/**
 .......
+```
+
+### az-sync action
+
+**Path:** `.github/actions/az-sync/action.yml`
+
+A reusable composite action that logs into Azure, retrieves secrets from an Azure Key Vault, and exports them as environment variables for use in subsequent workflow steps. After all secrets are synced, it logs out of Azure automatically.
+
+#### Inputs
+
+| Input | Description | Required | Default |
+|---|---|---|---|
+| `az_client_id` | Azure Client ID (for OIDC federated login) | Yes | — |
+| `az_tenant_id` | Azure Tenant ID | Yes | — |
+| `az_subscription_id` | Azure Subscription ID | Yes | — |
+| `keyvault` | Name of the Azure Key Vault to read secrets from | Yes | — |
+| `secrets-filter` | Comma-separated list (no spaces) of secret name patterns to sync | Yes | `*` |
+
+#### Usage example
+
+```yml
+- name: Get Secrets from Azure Key Vault
+  uses: nginxinc/docs-actions/.github/actions/az-sync@nginx.org
+  with:
+    az_client_id: ${{ secrets.AZURE_VAULT_CLIENT_ID }}
+    az_tenant_id: ${{ secrets.AZURE_VAULT_TENANT_ID }}
+    az_subscription_id: ${{ secrets.AZURE_VAULT_SUBSCRIPTION_ID }}
+    keyvault: ${{ secrets.DOCS_VAULTNAME }}
+    secrets-filter: 'MySecret1,MySecret2'
+```
+
+Each matched secret is exported as an environment variable named after the secret (e.g. `MySecret1`). Multiline secret values are handled using the heredoc syntax supported by `$GITHUB_ENV`.
+
+---
+
+### nginx.org-make-aws workflow
+
+**Path:** `.github/workflows/nginx.org-make-aws.yml`
+
+A reusable (`workflow_call`) workflow that builds the nginx.org website using `make` and deploys it to AWS S3. It supports two separate jobs controlled by the `deployment_env` input:
+
+- **`build-staging`** — Builds the site from source and syncs the output to a versioned staging path in S3 (`staging/<sha>/`). Also uploads a `.deployed.txt` marker file used by the production job.
+- **`build-prod`** — Waits for the staging marker to be present for the current commit SHA, then promotes the staged build to the production S3 path (`prod/`).
+
+Both jobs use the [az-sync](#az-sync-action) action to retrieve AWS credentials from Azure Key Vault before assuming an AWS IAM role via OIDC.
+
+#### Secrets
+
+| Secret | Description | Required |
+|---|---|---|
+| `AZURE_VAULT_CLIENT_ID` | Azure Client ID for Key Vault access | Yes |
+| `AZURE_VAULT_SUBSCRIPTION_ID` | Azure Subscription ID | Yes |
+| `AZURE_VAULT_TENANT_ID` | Azure Tenant ID | Yes |
+| `DOCS_VAULTNAME` | Name of the Azure Key Vault containing AWS credentials | Yes |
+
+The Key Vault referenced by `DOCS_VAULTNAME` must contain the following secrets:
+
+| Key Vault secret | Description |
+|---|---|
+| `NginxOrgAwsAccountID` | AWS account ID used to construct the IAM role ARN |
+| `NginxOrgAwsRoleName` | AWS IAM role name to assume via OIDC |
+| `NginxOrgAllowedUsers` | Comma-separated list of GitHub usernames allowed to trigger production deployments |
+
+#### Inputs
+
+| Input | Description | Required | Default |
+|---|---|---|---|
+| `deployment_env` | Target environment: `staging` or `prod` | No | `staging` |
+| `url_prod` | Public hostname for the production site | No | `nginx.org` |
+| `url_staging` | Public hostname for the staging site | No | `staging.nginx.org` |
+| `s3_bucket` | S3 bucket name for deployments | No | `nginx-org-staging` |
+| `aws_region` | AWS region for S3 operations | No | `eu-central-1` |
+
+#### Access controls
+
+Both jobs verify that the workflow is triggered from an allowed context before proceeding:
+
+- **Organization**: `nginx` or `nginxinc`
+- **Event**: `push` or `workflow_dispatch`
+- **Ref** (prod only): `refs/heads/main`
+- **Actor** (prod only): must be listed in the `NginxOrgAllowedUsers` Key Vault secret
+
+#### Caller example
+
+```yml
+name: nginx.org build and deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      deployment_env:
+        description: 'Target environment'
+        required: false
+        default: staging
+        type: choice
+        options:
+          - staging
+          - prod
+
+jobs:
+  call-nginx-org-build:
+    uses: nginxinc/docs-actions/.github/workflows/nginx.org-make-aws.yml@main
+    with:
+      deployment_env: ${{ inputs.deployment_env || 'staging' }}
+    secrets:
+      AZURE_VAULT_CLIENT_ID: ${{ secrets.AZURE_VAULT_CLIENT_ID }}
+      AZURE_VAULT_SUBSCRIPTION_ID: ${{ secrets.AZURE_VAULT_SUBSCRIPTION_ID }}
+      AZURE_VAULT_TENANT_ID: ${{ secrets.AZURE_VAULT_TENANT_ID }}
+      DOCS_VAULTNAME: ${{ secrets.DOCS_VAULTNAME }}
+```