pulumi
diff --git a/‎content/docs/iac/neo/_index.md
Lines changed: 68 additions & 0 deletions b/‎content/docs/iac/neo/_index.md
Lines changed: 68 additions & 0 deletions
diff --git a/‎content/docs/iac/neo/get-started/_index.md
Lines changed: 92 additions & 0 deletions b/‎content/docs/iac/neo/get-started/_index.md
Lines changed: 92 additions & 0 deletions
diff --git a/‎content/docs/iac/neo/pull-requests/_index.md
Lines changed: 57 additions & 0 deletions b/‎content/docs/iac/neo/pull-requests/_index.md
Lines changed: 57 additions & 0 deletions
diff --git a/‎content/docs/iac/neo/pull-requests/pr-example.png
246 KB b/‎content/docs/iac/neo/pull-requests/pr-example.png
246 KB
diff --git a/‎content/docs/iac/neo/running-previews/_index.md
Lines changed: 103 additions & 0 deletions b/‎content/docs/iac/neo/running-previews/_index.md
Lines changed: 103 additions & 0 deletions
diff --git a/‎content/docs/iac/neo/running-previews/preview-output.png
220 KB b/‎content/docs/iac/neo/running-previews/preview-output.png
220 KB
diff --git a/‎content/docs/iac/neo/running-previews/preview-prompt.png
13.7 KB b/‎content/docs/iac/neo/running-previews/preview-prompt.png
13.7 KB
diff --git a/‎content/docs/iac/neo/tasks/_index.md
Lines changed: 71 additions & 0 deletions b/‎content/docs/iac/neo/tasks/_index.md
Lines changed: 71 additions & 0 deletions
diff --git a/‎content/docs/iac/neo/tasks/entity-context.png
22.3 KB b/‎content/docs/iac/neo/tasks/entity-context.png
22.3 KB
@@ -0,0 +1,68 @@
+---
+title_tag: "Pulumi Neo"
+meta_desc: Pulumi Neo is an agentic AI that enables conversational infrastructure management through natural language interactions.
+title: Pulumi Neo
+h1: Pulumi Neo
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Neo
+        parent: iac-home
+        weight: 22
+        identifier: iac-neo
+---
+
+## Overview
+
+Neo is a purpose-built infrastructure automation agent that can carry out platform engineering tasks on your behalf. Neo enables platform engineers to make natural language requests, which Neo autonomously plans and executes. Rather than writing code or running CLI commands for routine tasks, you can simply tell Neo what you need:
+
+- "Find all Lambda functions running deprecated runtimes and upgrade them"
+- "Fix the S3 buckets that violate our security policies"
+- "Analyze what resources depend on our production database"
+
+Beyond maintenance and analysis, Neo can create new infrastructure resources, remove unused components, and refactor code into reusable modules. Neo works across multiple stacks in a single task when needed, like updating connection strings everywhere at once or applying security policies across your entire infrastructure.
+
+Neo understands your intent, creates an execution plan, and handles the implementation through existing [GitHub workflows](/docs/iac/using-pulumi/continuous-delivery/github-actions/) and [Pulumi operations](/docs/iac/cli/).
+
+### Key benefits
+
+#### Accelerate Delivery
+
+Automate multi-step workflows and routine maintenance to respond faster to development team needs and infrastructure requirements.
+
+#### Reduce Context Switching
+
+Platform teams manage infrastructure across multiple repositories, clouds, and tools. Neo understands this complexity and can work across your entire infrastructure landscape, eliminating the need to context-switch between different systems.
+
+#### Focus on Strategic Work
+
+Neo handles routine infrastructure tasks that consume platform engineering time. Policy violations, runtime upgrades, and dependency analysis can be delegated to Neo, freeing your team to focus on architecture, optimization, and innovation.
+
+#### Maintain Control and Compliance
+
+Every change Neo makes goes through [pull requests](/docs/iac/neo/pull-requests/), ensuring human review and your existing CI/CD pipeline validations. Neo operates within the [RBAC boundaries](/docs/pulumi-cloud/access-management/rbac/) of the user making the request and automatically enforces your [Pulumi policies](/docs/iac/crossguard/).
+
+## How Neo Fits into Pulumi
+
+Neo complements and enhances your existing Pulumi workflows
+
+- **Pulumi IaC**: Neo generates and modifies Pulumi infrastructure code, working with your existing [programs](/docs/iac/concepts/projects/) and [stacks](/docs/iac/concepts/stacks/)
+- **Pulumi ESC**: Neo uses [ESC](/docs/esc/) for secure credential management, enabling it to run previews and validate changes
+- **Pulumi Policies**: Neo automatically respects and enforces your [policy packs](/docs/iac/crossguard/), preventing non-compliant changes
+- **Pulumi Cloud**: Neo leverages [Pulumi Cloud's](/docs/pulumi-cloud/) infrastructure graph to understand dependencies and impacts
+
+## Tasks
+
+[Tasks](/docs/iac/neo/tasks/) are how Neo plans and executes multi-step operations while maintaining safety through comprehensive controls.
+
+Safety is maintained through [policy controls](/docs/iac/crossguard/) that define guardrails for Neo's operations, ensuring all changes align with your organization's standards and compliance requirements.
+
+## Human-in-the-loop workflows
+
+Neo ensures that critical decisions require human approval and all infrastructure changes go through your existing review processes. This approach provides:
+
+- **Pull request-based changes**: All infrastructure modifications are proposed through PRs, maintaining your standard code review workflow
+- **Approval gates**: Intensive operations, such as running [Pulumi preview](/docs/iac/neo/running-previews/), pause for explicit human authorization before proceeding
+- **Audit trails**: Complete visibility into what Neo planned, executed, and why
+
+This design gives you the benefits of automation while preserving the control and oversight essential for production infrastructure management.
@@ -0,0 +1,92 @@
+---
+title: Getting started with Neo
+title_tag: Getting started with Pulumi Neo
+h1: Getting started with Pulumi Neo
+meta_desc: Learn how to set up Pulumi Neo for your organization and run your first infrastructure task through conversational AI.
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Get started
+        parent: iac-neo
+        weight: 10
+        identifier: iac-neo-get-started
+    neo:
+        name: Get started
+        weight: 1
+---
+
+## Public Preview Access
+
+Neo is in public preview and currently free to use. Users will receive ample warning before any pricing changes go into effect. Using Neo to optionally run [`pulumi preview`](/docs/iac/neo/running-previews/) consumes workflow minutes. Lean more about workflow minutes on our [pricing page](https://www.pulumi.com/pricing/#faq-pricing).
+
+## Enabling and Disabling Neo
+
+Neo is enabled by default. To disable Neo for your organization, navigate to the [Access Management page](/docs/pulumi-cloud/access-management/), under the Settings section. AI features can be enabled or disabled in the Pulumi Copilot section. If Copilot was previously disabled, it will need to be enabled to use Neo.
+
+## GitHub App Installation
+
+Installing the [Pulumi GitHub App](/docs/iac/using-pulumi/continuous-delivery/github-app/) significantly enhances Neo's capabilities, though it is not required. The Pulumi GitHub App:
+
+- Allows Neo to read repository content for better context
+- Enables pull request creation
+- Streamlines the code change workflow
+
+Neo can still provide code change suggestions without the GitHub App, but you'll need to apply the changes and open PRs manually.
+
+To install the GitHub App, see the [GitHub integration guide](/docs/iac/using-pulumi/continuous-delivery/github-app/).
+
+## Neo's Permission Model
+
+Neo operates within the conversing user's [RBAC entitlements](/docs/pulumi-cloud/access-management/rbac/) and cannot perform actions that the user couldn't perform themselves. This means:
+
+- There's no privilege escalation risk or special administrative access required
+- Each user's Neo conversations are isolated from other users
+
+## Quick Start Guide
+
+### Enable Neo for Your Organization
+
+Neo is automatically enabled for eligible organizations. To access Neo:
+
+1. Navigate to [Pulumi Cloud](https://app.pulumi.com)
+2. Click on **Agent Tasks** within the **Neo** section in the left navigation menu
+
+> If Neo doesn't appear in your navigation, verify that AI features have not been disabled for your organization. AI controls are located on the [Access Management page](/docs/pulumi-cloud/access-management/), in the Pulumi Copilot section.
+
+### Create Your First Task
+
+Each conversation with Neo is called a "task" - a contained unit of work where Neo helps you accomplish a specific infrastructure goal.
+
+Let's run a simple infrastructure [task](/docs/iac/neo/tasks/) to see Neo in action
+
+1. Start with a read-only analysis task by prompting Neo:
+
+    `Which of my resources are not using their latest major version?`
+
+2. Neo will:
+   - Acknowledge your request
+   - Search through your infrastructure
+   - Present findings in a clear format
+
+3. As a follow-up, ask Neo what you should address first:
+
+    `Which version issue should I address first?`
+
+4. Neo will respond with a plan to address the most important outdated version it found. Go ahead and ask it to propose a change for the highest priority finding:
+
+    `Can you propose the necessary code change to address the highest priority item?`
+
+5. Depending on the scale of the issue, Neo may propose a plan for addressing it; or, Neo may get to work right away to create a PR. Neo will then:
+
+   - Ask for confirmation before making changes
+   - Generate the necessary code modifications
+   - Request approval before opening a [pull request](/docs/iac/neo/pull-requests/)
+   - Create a [PR](/docs/iac/neo/pull-requests/) with clear documentation of the changes
+
+## Considerations and Limitations
+
+- GitHub Only - Neo only works with GitHub repositories. GitLab, Bitbucket, and other platforms are not supported yet.
+- Tasks Cannot Be Shared - Each task is private to the user who created it. Tasks cannot be shared, transferred, or collaborated on between team members.
+- Code Changes Only - Neo can only modify infrastructure through code. It cannot perform API or UI actions like configure deployments, updating stack configurations, or managing environments in Pulumi Cloud.
+- Cannot Create GitHub Repos - Neo cannot create new GitHub repositories or initialize new Git repos. It only works within existing repositories.
+- Cannot Create New Projects - Neo cannot initialize new Pulumi projects. It can only work within existing projects that are already set up.
@@ -0,0 +1,57 @@
+---
+title: Pull requests
+title_tag: Pull requests with Pulumi Neo
+h1: Pull requests with Pulumi Neo
+meta_desc: Learn how Neo creates and manages pull requests to implement infrastructure changes through your existing review process.
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Pull requests
+        parent: iac-neo
+        weight: 30
+        identifier: iac-neo-pull-requests
+    neo:
+        name: Pull requests
+        weight: 3
+---
+
+Pull requests are the bridge between Neo's AI capabilities and your production infrastructure. Every change Neo proposes goes through a PR, ensuring:
+
+- Human review of all changes
+- CI/CD pipeline validation
+- Team collaboration and knowledge sharing
+- Audit trail and rollback capability
+
+## Prerequisites
+
+At this time, Neo only supports reading code from and creating pull requests in GitHub.
+
+### GitHub App Installation
+
+Neo requires the [Pulumi GitHub App](/docs/iac/using-pulumi/continuous-delivery/github-app/) to be installed to create pull requests. Additionally, without the Pulumi GitHub App, Neo will not be able to view the IaC code backing a stack. Neo can still propose code changes, but they will not be fully contextualized to your IaC code.
+
+### Code Access
+
+When a stack is created, its git location is added as stack tags. Neo uses these tags to locate and fetch the git repository.
+
+### Pull Requests
+
+Neo will offer to open a pull request after a preview is run. You can also ask Neo to open or update a pull request at any time. Neo opens a PR with:
+
+- Clear title describing the change
+- Description of what problem it solves
+- List of modified resources
+- Preview output summary
+- Link back to the Neo task
+
+![Example PR](pr-example.png)
+
+### Requesting Changes
+
+When reviewing Neo's pull requests, you can ask for modifications through follow-up prompting. Neo understands context from both the PR and your conversation history.
+
+### GitHub Actions Integration
+
+If you use GitHub Actions for CI/CD, Neo's pull requests can automatically trigger your existing workflows. When configured, your Pulumi previews, security scans, policy checks, and tests will run automatically on Neo's PRs, just like any other pull request. If a workflow fails, you can ask Neo to address the specific issue, and it will push fixes to the same PR.
+
+To set up GitHub Actions with Pulumi, see the [GitHub Actions documentation](/docs/iac/using-pulumi/continuous-delivery/github-actions/).
@@ -0,0 +1,103 @@
+---
+title: Previews
+title_tag: Running previews with Pulumi Neo
+h1: Running previews with Pulumi Neo
+meta_desc: Learn how Neo uses Pulumi preview to validate infrastructure changes before creating pull requests.
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Previews
+        parent: iac-neo
+        weight: 20
+        identifier: iac-neo-running-previews
+    neo:
+        name: Previews
+        weight: 2
+---
+
+Neo can run [preview](/docs/iac/cli/commands/pulumi_preview/) directly from Pulumi Cloud to validate proposed infrastructure changes before creating pull requests. This capability provides confidence that suggested modifications do not result in unexpected resource changes and comply with [policies](/docs/iac/crossguard/).
+
+## Public Preview Access
+
+Neo is in public preview and currently free to use. Users will receive ample warning before any pricing changes go into effect. Using Neo to optionally run `pulumi preview` consumes workflow minutes. Lean more about workflow minutes on our [pricing page](https://www.pulumi.com/pricing/#faq-pricing).
+
+## Prerequisites
+
+### Configuration and Credentials
+
+To execute a `pulumi preview`, Neo needs the necessary configuration and credentials.
+
+- Applicable cloud provider credentials, such as [AWS](https://www.pulumi.com/registry/packages/aws/installation-configuration/#set-credentials-as-environment-variables), [Azure](https://www.pulumi.com/registry/packages/azure-native/installation-configuration/#set-configuration-using-environment-variables), or [GCP](https://www.pulumi.com/registry/packages/gcp/installation-configuration/#authenticate-using-a-service-account.)
+- Any additional configuration required by your Pulumi programs
+
+ The configuration and credentials can be supplied via [stack config](/docs/iac/concepts/config/) or an [ESC environment](/docs/esc/environments/).
+
+### Stack Config
+
+[Stack configuration](/docs/iac/concepts/config/) is a method of defining configuration directly on a stack, such as through the Pulumi CLI, a stack config file, or API.
+
+### ESC Stack Association
+
+Using [ESC](https://www.pulumi.com/docs/esc/) is the recommended approach for defining stack configuration and secrets. It is the most flexible and scalable option, and has native OIDC integration with all of the major cloud providers.
+
+Learn more about [ESC](/docs/esc/) and [associating an ESC](/docs/esc/integrations/infrastructure/pulumi-iac/) environment with a stack.
+
+## Using previews
+
+When you ask Neo to make infrastructure changes, it utilizes previews to:
+
+1. **Validate proposed changes**: Ensure the generated code is syntactically correct and will execute successfully
+2. **Show impact analysis**: Display what resources will be created, updated, or deleted
+3. **Check policy compliance**: Verify changes comply with your organization's [CrossGuard policies](/docs/iac/crossguard/)
+
+### Preview Workflow
+
+Once Neo has arrived at a solution for solving a task, it will request to run a `preview` to validate the changes. You can approve or decline the request. You can also manually run a preview at any time by simply prompting Neo.
+
+ ![Neo asking to run a preview](preview-prompt.png)
+
+Once the preview has executed, Neo will propose opening a pull request. You can approve opening a PR, or request that Neo make changes to its proposal.
+
+![Neo asking to run a preview](preview-output.png)
+
+### Preview Output
+
+- Number of resources to be modified
+- Specific changes for each resource
+- Any errors or warnings
+- Policy violations if applicable
+
+### Policy Compliance Checking
+
+If the stack executing the `preview` is associated with Pulumi IaC policies, the policies will be exercised as part of the preview, and any warnings or violations will be displayed.
+
+## Troubleshooting
+
+### Missing or Invalid Credentials
+
+If Neo cannot run previews due to missing credentials:
+
+1. Verify your ESC environment contains the necessary credentials
+2. Check that the environment is associated with your stack. You can visit the stack details page to view the associated ESC environments.
+
+## Best practices
+
+### Always Preview Before Merging
+
+While Neo runs previews before creating PRs, always run a final preview before merging to catch any changes that occurred since PR creation.
+
+### Review Preview Output Carefully
+
+Pay special attention to:
+
+- Resources marked for replacement (not just update)
+- Unexpected resources in the change set
+- Policy warnings or violations
+
+## Security Considerations
+
+Neo's preview operations are limited by:
+
+- The permissions of the user initiating the request
+- The IAM roles associated with ESC credentials
+- Organization-level policies and restrictions
@@ -0,0 +1,71 @@
+---
+title: Tasks
+title_tag: Tasks in Pulumi Neo
+h1: Tasks in Pulumi Neo
+meta_desc: Learn about tasks, the primary entity for interacting with Neo to perform infrastructure operations.
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Tasks
+        parent: iac-neo
+        weight: 15
+        identifier: iac-neo-tasks
+    neo:
+        name: Tasks
+        weight: 1.5
+---
+
+Tasks are Neo's primary unit of work. Each task represents a distinct conversation where you describe what you want to accomplish, and Neo plans and executes the necessary infrastructure changes. Tasks provide structure, context, and boundaries for Neo's operations.
+
+## Key Characteristics
+
+### User Isolation
+
+Tasks are completely isolated between users:
+
+- Each task belongs exclusively to the user who created it
+- Tasks cannot be shared, transferred, or viewed by other users
+- User permissions and [RBAC](/docs/pulumi-cloud/access-management/rbac/) are enforced within each task
+- Conversation history and context remain private to the creating user
+
+This isolation prevents the opportunity for escalation.
+
+### Task Plans
+
+When you give Neo a complex request, it creates a task plan outlining the steps it will take to accomplish your goal. This plan provides transparency into Neo's approach and gives you the opportunity to adjust the strategy before execution begins.
+
+#### Example Plan
+
+The following is a representative plan in response to a user requesting to locate and update outdated Lambda functions:
+
+1. Identify all Lambda functions using Node.js
+2. Determine the appropriate target runtime for each
+3. Create code changes to update the runtime versions
+4. Run a preview to validate all changes
+5. Create a pull request with the updates
+
+### Approvals
+
+Neo will seek approval before opening a PR or running a preview.
+
+### Pulumi Previews
+
+At any time, you can explicitly ask Neo to run a [pulumi preview](/docs/iac/cli/commands/pulumi_preview/). As well, if Neo proposes code changes as part of a task, it will request to run a preview to help obtain feedback on the changes. [Learn more](/docs/iac/neo/running-previews/) about Neo and previews.
+
+### Pull Requests
+
+If a task results in Neo proposing code modifications, it will offer to open a [pull request](/docs/iac/neo/pull-requests/) once the user is satisfied with the implementation. PRs can also be modified after they've been opened.
+
+## Setting the Entity Context
+
+You can explicitly set the [stack](/docs/iac/concepts/stacks/) and [repository](/docs/iac/concepts/projects/) context when initiating a task. This helps Neo understand exactly where to focus its operations.
+
+![Neo asking to run a preview](entity-context.png)
+
+## Interruptions and Resuming
+
+Tasks continue running even if you close your browser or navigate away. When you return to the task later, Neo will have continued working and will show you any progress made while you were away. You can pick up the conversation exactly where you left off, with full context preserved.
+
+## Task History
+
+Neo tasks are saved and accessible through the Agent Tasks page in Pulumi Cloud. Though the entire task history is available at any time, the task cache may be lost if the agent idles for an hour or more.