Merge branch 'main' into docs/namespace-guidance-consolidation

Author: brianmacdonald-temporal

.github/workflows/docs-preview-links.yml

@@ -26,26 +26,16 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Compute preview base URL
+      - name: Get preview URL from Vercel comment
         id: preview-url
-        env:
-          REPO_PREVIEW_BASE_URL: ${{ vars.DOCS_PREVIEW_BASE_URL }}
-          REPO_PREVIEW_TEMPLATE: ${{ vars.DOCS_PREVIEW_BASE_URL_TEMPLATE }}
-        run: |
-          BRANCH_NAME="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
-          BRANCH_SLUG=$(echo "$BRANCH_NAME" | tr '[:upper:]' '[:lower:]' | tr -d '_' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
-
-          if [ -n "$REPO_PREVIEW_BASE_URL" ]; then
-            BASE_URL="$REPO_PREVIEW_BASE_URL"
-          elif [ -n "$REPO_PREVIEW_TEMPLATE" ]; then
-            BASE_URL="${REPO_PREVIEW_TEMPLATE//\{branch\}/$BRANCH_SLUG}"
-          else
-            BASE_URL="https://temporal-documentation-git-${BRANCH_SLUG}.preview.thundergun.io"
-          fi
-
-          echo "DOCS_PREVIEW_BASE_URL=$BASE_URL" >> "$GITHUB_ENV"
-          echo "BRANCH_SLUG=$BRANCH_SLUG" >> "$GITHUB_ENV"
-          echo "base_url=$BASE_URL" >> "$GITHUB_OUTPUT"
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { resolvePreviewUrl } = require('./bin/preview-url-from-vercel.js');
+            const baseUrl = await resolvePreviewUrl({ github, context, core });
+            core.exportVariable('DOCS_PREVIEW_BASE_URL', baseUrl);
+            core.setOutput('base_url', baseUrl);
 
       - name: Generate docs preview list
         env:

COMPONENTS.md

@@ -137,6 +137,21 @@ Usage:
 
 Images are normally stored in the '/static' folder in `img` or `diagrams`.
 
+### Dark mode images
+
+To provide a separate image for dark mode, use the `srcDark` prop:
+
+```
+<CaptionedImage
+    src="/diagrams/my-diagram.svg"
+    srcDark="/diagrams/my-diagram-dark.svg"
+    title="My diagram"
+    alt="Description of the diagram"
+/>
+```
+
+When `srcDark` is provided, both images are rendered in the DOM and the browser loads both upfront. CSS toggles visibility based on the active theme, so switching between light and dark mode is instant with no loading delay. When `srcDark` is omitted, the component renders a single image as usual.
+
 ### Zooming images
 
 When images are complex and may not render in a readable fashion on normal monitors, you can enable a minimal form of zooming by setting the `zoom` prop to true:

bin/preview-url-from-vercel.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const MAX_SUBDOMAIN_LENGTH = 63;
+const MAX_ATTEMPTS = 18;
+const INTERVAL_MS = 10_000;
+const PREVIEW_DOMAIN = 'preview.thundergun.io';
+
+function branchToSlug(branchName) {
+  return branchName
+    .toLowerCase()
+    .replace(/_/g, '')
+    .replace(/[^a-z0-9]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-/, '')
+    .replace(/-$/, '');
+}
+
+function buildSubdomain(branchSlug) {
+  return `temporal-documentation-git-${branchSlug}`;
+}
+
+function extractPreviewUrlFromComment(body) {
+  const match = body.match(/\[vc\]:\s*#[^:]*:(eyJ[A-Za-z0-9+/=]+)/);
+  if (!match) return null;
+
+  const payload = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8'));
+  return payload.projects?.[0]?.previewUrl || null;
+}
+
+async function resolvePreviewUrl({ github, context, core }) {
+  const branchName = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+  const branchSlug = branchToSlug(branchName);
+  const subdomain = buildSubdomain(branchSlug);
+
+  if (subdomain.length <= MAX_SUBDOMAIN_LENGTH) {
+    const baseUrl = `https://${subdomain}.${PREVIEW_DOMAIN}`;
+    core.info(`Branch name is short enough (${subdomain.length} chars), using constructed URL: ${baseUrl}`);
+    return baseUrl;
+  }
+
+  core.info(`Subdomain would be ${subdomain.length} chars (exceeds ${MAX_SUBDOMAIN_LENGTH}), polling for Vercel comment...`);
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    core.info(`Polling for Vercel comment (attempt ${attempt}/${MAX_ATTEMPTS})...`);
+    const { data: comments } = await github.rest.issues.listComments({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: context.issue.number,
+      per_page: 100,
+    });
+
+    const vercelComment = comments.find(
+      (c) => c.user?.login === 'vercel[bot]' && c.body?.includes('[vc]:'),
+    );
+
+    if (vercelComment) {
+      const previewUrl = extractPreviewUrlFromComment(vercelComment.body);
+      if (previewUrl) {
+        const baseUrl = `https://${previewUrl}`;
+        core.info(`Found Vercel preview URL: ${baseUrl}`);
+        return baseUrl;
+      }
+    }
+
+    if (attempt < MAX_ATTEMPTS) {
+      await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
+    }
+  }
+
+  core.warning('Vercel comment not found after polling, using constructed URL as fallback (links may be broken for this long branch name)');
+  return `https://${subdomain}.${PREVIEW_DOMAIN}`;
+}
+
+module.exports = { resolvePreviewUrl, branchToSlug, buildSubdomain, extractPreviewUrlFromComment };

docs/best-practices/cloud-access-control.mdx

@@ -22,6 +22,13 @@ Temporal Cloud supports two secure authentication methods for Workers:
 
 Both options help secure communication between workers and Temporal Cloud. Choosing the right method and managing it properly is key to maintaining security and minimizing downtime. 
 
+Use this page to define your operating model for machine access to Temporal Cloud. For setup steps and product-specific
+mechanics, see [Manage API keys](/cloud/api-keys) and [Manage service accounts](/cloud/service-accounts).
+
+Related guidance:
+- [Namespace best practices](/best-practices/managing-namespace)
+- [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns)
+
 The high-level end-to-end rotation process is:
 
 1. **Generate new credentials**: Create new certificates or API keys in Temporal Cloud before the current ones expire
@@ -45,17 +52,64 @@ In the case that you are using multiple certificates signed by the same CA, and
 
 One convention is to give certificates a common name that matches the namespace. If you do this when using the same CA for dev and prod, then you can leverage Certificate Filters to prevent access to production environments. This is described in detail under the [authorization section](https://docs.temporal.io/cloud/certificates#control-authorization) of the documentation. 
 
-## Best practices: 
-#### 1. Establish clear guidelines on authentication methods: Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or [API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
+## Best practices
+
+### Establish clear guidelines on authentication methods
+
+Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or
+[API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
 - Connect Temporal clients to Temporal Cloud (e.g. Worker processes)
 - Automation (e.g. Temporal Cloud [Operations API](https://docs.temporal.io/ops), [Terraform provider](https://docs.temporal.io/cloud/terraform-provider), [Temporal CLI](https://docs.temporal.io/cli/setup-cli))
 
-    By default, it is recommended for teams to use API keys and [service accounts](https://docs.temporal.io/cloud/service-accounts) for both operations because API keys are easier to manage and rotate for most teams. In addition, you can control account-level and namespace-level roles for service accounts. 
+By default, teams should use API keys with [service accounts](/cloud/service-accounts) for both operations. API keys
+are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and
+namespace-level roles.
+
+If your organization requires mutual authentication and stronger cryptographic guarantees, use
+[mTLS certificates](/cloud/certificates) to authenticate Temporal clients to Temporal Cloud and use API keys for
+automation, because the Temporal Cloud [Operations API](/ops) and [Terraform provider](/cloud/terraform-provider) only
+support API key authentication. Unlike API keys tied to users or service accounts, mTLS certificate authentication is
+not tied to Temporal Cloud RBAC identities. Namespace access is based on CA trust, with optional
+[Certificate Filters](/cloud/certificates#manage-certificate-filters) to narrow access by Common Name.
+
+### Default operating model for service accounts and API keys
+
+For most organizations, use the following defaults:
+
+- Create one Service Account per service or worker deployment, not one shared Service Account for an entire team
+- Use account-level Service Accounts only when a service genuinely needs cross-Namespace or account-wide access
+- Prefer Namespace-scoped Service Accounts when a service should only access one Namespace
+- Grant Service Accounts namespace-level access only to the specific Namespaces they need
+
+This approach gives you cleaner ownership, easier rotation, and better auditability than sharing a single machine
+identity across multiple services.
+
+### Use access boundaries that match your Namespace boundaries
+
+The way you partition Namespaces should usually match the way you partition machine identities.
+
+- If multiple services share a Namespace, you may still want one Service Account per service so that each deployment can
+  rotate credentials independently.
+- If you split workloads into separate Namespaces for security, capacity, or team ownership reasons, those Namespaces
+  should usually have separate Service Accounts and API keys as well.
+- If you use Namespace-per-tenant isolation, expect your credential model and RBAC model to become correspondingly more
+  granular.
+
+For more on topology tradeoffs, see [Namespace best practices](/best-practices/managing-namespace) and
+[Multi-tenant application patterns](/production-deployment/multi-tenant-patterns).
+
+### Rotate credentials without downtime
+
+Use the following sequence when rotating credentials:
 
-    If your organization requires mutual authentication and stronger cryptographic guarantees, then it is encouraged for your teams to use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation (because Temporal Cloud [Operations API](https://docs.temporal.io/ops) and [Terraform provider](https://docs.temporal.io/cloud/terraform-provider) only supports API key for authentication)
+1. Create the replacement credential before the existing one expires.
+2. For API keys, create the new valid key while the old key still works, then roll your Workers and clients to use the new key.
+3. For client certificates, stage the new certificate before removing the old one when your deployment process supports that transition.
+4. Validate connectivity and normal Workflow execution using the new credential.
+5. Remove the old credential only after all clients and Workers have switched.
 
-#### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`):
+### Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`)
 
-  Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.   
+Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.   
 
-  If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production. 
+If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production. 

docs/best-practices/cost-optimization.mdx

@@ -62,7 +62,7 @@ See [Spooky Stories: Chilling Temporal Anti-Patterns](https://temporal.io/blog/s
 ### Large payloads in Workflow History
 
 Passing multi-megabyte payloads through Workflows when external storage (S3, blob storage) is more appropriate.
-Use [compression](/troubleshooting/blob-size-limit-error#why-does-this-error-occur) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
+Use [compression](/troubleshooting/blob-size-limit-error#payload-size-limit) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
 
 ### Over-optimization at the expense of observability
 
@@ -137,7 +137,7 @@ For detailed discussion of this tradeoff, see [How many Activities should I use
 
 ### Child Workflows vs Activities
 
-[Child Workflows cost 2 Actions](/cloud/actions#child-workflows) compared to an Activity's 1 Action.
+[Child Workflows cost 2 Actions](/cloud/actions#workflow) compared to an Activity's 1 Action.
 See [Child Workflows documentation](/child-workflows) for detailed comparison of capabilities and use cases.
 
 ### Retry Policies
@@ -165,7 +165,7 @@ Refer to this blog post on [Mastering Workflow retry logic for resilient applica
 ### Local Activities
 
 A [Local Activity](/local-activity#local-activity) is an Activity Execution that executes in the same process as the Workflow Execution that spawns it.
-Therefore, multiple Local Activities that run back-to-back only [count as a single billable action](/cloud/actions#activities), whereas each regular Activity counts as a billable action.
+Therefore, multiple Local Activities that run back-to-back only [count as a single billable action](/cloud/actions#activity), whereas each regular Activity counts as a billable action.
 However, there are tradeoffs to converting regular Activities to Local Activities.
 For example, if a specific Local Activity fails, *all* of them will be retried together.
 Review [the docs](/local-activity) or reach out to your account team to learn more.
@@ -189,7 +189,7 @@ Use Regular Activities instead of Local Activities if you require any of the fol
 2. For Search Attributes that must be updated during Workflow Execution, each `UpsertSearchAttributes` call counts as 1 Action regardless of how many attributes are updated.
    Batch multiple related attribute updates into single operations to reduce Actions consumed.
 
-See the [Temporal Cloud Action Documentation](/cloud/actions#workflows) for details.
+See the [Temporal Cloud Action Documentation](/cloud/actions#workflow) for details.
 
 #### Signal handling
 
@@ -252,7 +252,7 @@ Alternatively, if you are looking to do analysis on closed Workflow Executions,
 ### Validation approach
 
 1. **Test in non-production**: Validate functional correctness before production deployment
-2. **Monitor comprehensively**: Leverage the [Usage dashboard](/cloud/actions#usage) in the Cloud UI to track the impact on Actions and Storage after optimizations are made
+2. **Monitor comprehensively**: Leverage the [Usage dashboard](/cloud/actions-usage#usage) in the Cloud UI to track the impact on Actions and Storage after optimizations are made
 3. **Progressive rollout**: Deploy to a small percentage, validate, then expand. Review the [Worker Versioning documentation](/production-deployment/worker-deployments/worker-versioning) to learn about rolling out changes to Workflows
 4. **Continuous review**: Re-evaluate optimization effectiveness quarterly as system evolves