Skip to content

ESC environment docs link to Automation API page with no ESC coverage; language matrix missing Java #20634

Description

@workprentice

content/docs/esc/concepts/environments.md links to /docs/iac/concepts/automation-api/
in two places when describing how Automation API manages a stack's imported ESC
environments — but that page has no ESC-environment coverage at all. The actual
addEnvironments/listEnvironments/removeEnvironment documentation, including
per-language examples, lives at /docs/esc/integrations/automation-api/. A reader
following either link lands on a page that doesn't answer the question that sent them
there.

Separately, the language-support matrix on
content/docs/esc/integrations/automation-api.md lists TypeScript/JavaScript, Python,
Go, and C#, but omits Java, even though the Java Automation API SDK
(com.pulumi.automation.WorkspaceStack) supports addEnvironments and
removeEnvironment (no list method, matching the .NET SDK's gap) and the page's own
narrative examples elsewhere in the docs already include a Java chooser tab for other
Automation API topics.

Finally, none of the narrative Automation API pages
(content/docs/iac/concepts/automation-api.md,
content/docs/iac/guides/building-extending/automation-api.md,
content/docs/iac/guides/building-extending/automation-api-advanced.md) cross-link to
the ESC integration page, so a reader who starts from the general Automation API docs
has no path to discovering the ESC-environment methods at all.

Proposed fix

  1. Fix the two misdirected links in environments.md to point at
    /docs/esc/integrations/automation-api/.
  2. Add Java to the language-support matrix and chooser on
    content/docs/esc/integrations/automation-api.md, with a verified code example.
  3. Add short cross-references from the narrative Automation API pages to the ESC
    integration page.

Supporting signal

GA4 shows /docs/iac/concepts/automation-api/ (the misdirected link target) has a
below-average engagement rate for its traffic volume, consistent with readers arriving,
not finding what they need, and leaving quickly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions