If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pulumi/pulumi shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pulumi/pulumi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pulumi/pulumi.

What it runs against: a local clone of pulumi/pulumi — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pulumi/pulumi | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pulumi/pulumi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pulumi/pulumi.git
#   cd pulumi
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pulumi/pulumi and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pulumi/pulumi(\\.git)?\\b" \\
  && ok "origin remote is pulumi/pulumi" \\
  || miss "origin remote is not pulumi/pulumi (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "docs/architecture/README.md" \\
  && ok "docs/architecture/README.md" \\
  || miss "missing critical file: docs/architecture/README.md"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pulumi/pulumi"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pulumi is an infrastructure-as-code platform that lets you define cloud resources (AWS, Azure, GCP, Kubernetes, 120+ providers) using standard programming languages (Go, Python, TypeScript, C#, Java) instead of YAML or DSLs. It compiles language code to a resource engine that provisions and manages infrastructure declaratively, supporting loops, functions, and all language features for dynamic infrastructure. Monorepo with language-specific SDKs: the core Go engine (sdk/v3 per replace directive in go.mod) handles resource provisioning and state management; language bindings (sdk/python, sdk/nodejs, sdk/dotnet) expose this via gRPC. Workflows in .github/workflows/ orchestrate multi-SDK builds and tests. The repo includes devcontainer support (.devcontainer/) and Makefile-driven development.

DevOps engineers, platform teams, and SREs who want to codify infrastructure in familiar languages; developers building multi-cloud systems who need programmatic control over resource provisioning; teams seeking to reduce YAML boilerplate and use package management for infrastructure components.

Production-ready and actively maintained. The repo shows 16.9MB of Go code (core engine), well-established CI/CD workflows (45+ GitHub Actions in .github/workflows/), and broad language SDK support. The monorepo structure and comprehensive test infrastructure indicate a mature project backed by Pulumi Inc., with regular releases and active development.

Moderate complexity risk: the monorepo spans multiple language runtimes (Go + Python + TypeScript + C# SDKs), making cross-language bug fixes non-trivial. Dependency surface is large (120+ cloud providers). Single maintainer risk is low due to backing by Pulumi Inc., but breaking changes in the gRPC-based plugin protocol or state serialization could impact all SDKs and providers simultaneously.

Active CI/CD pipeline with release automation (ci-build-binaries.yml, release.yml), performance gating (ci-performance-gate.yml), and nightly test runs (cron-test-all.yml). The presence of Neo workflows (on-pr-neo.yml) and recent Homebrew integration suggests ongoing distribution and toolchain improvements. Version management via .github/scripts/versions.yaml indicates frequent release cycles.

Clone and explore: git clone https://github.com/pulumi/pulumi && cd pulumi. Check .devcontainer/devcontainer.json for container setup, or inspect the Makefile for local build targets. Install Go 1.25.8+ (from go.mod). Run make build to compile the CLI. For SDKs: cd sdk/python && pip install -e . or cd sdk/nodejs && npm install.

Daily commands: Development: make build compiles the CLI to bin/pulumi. For the Go engine: cd sdk && go build ./.... For Python SDK: cd sdk/python && python setup.py develop. For Node SDK: cd sdk/nodejs && npm install && npm run build. Run tests: make test or language-specific test commands in respective sdk/ subdirectories.

• README.md — Core value proposition and quick-start for Infrastructure as Code platform supporting multiple programming languages.
• Makefile — Build orchestration and primary entry point for compilation, testing, and release workflows across all SDKs.
• .github/workflows/ci.yml — Primary CI/CD pipeline defining test gates, binary builds, and SDK packaging for all supported languages.
• docs/architecture/README.md — High-level architectural overview documenting core abstractions: plugins, resources, providers, and deployment execution.
• .golangci.yml — Go linting configuration enforcing code quality standards across the Go SDK and CLI codebase.
• go.mod — Core module definition for Pulumi Go SDK with dependency versions critical to all Go-based providers.
• CONTRIBUTING.md — Contributor guidelines defining code style, PR process, and development environment setup for multi-language project.

Add a new Resource Provider

1. Study existing provider architecture and plugin system in docs/architecture/providers/implementers-guide.md to understand plugin protocol and resource schema (docs/architecture/providers/implementers-guide.md)
2. Create provider Go module following the plugin architecture (gRPC-based resource CRUD operations) (go.mod)
3. Implement resource schema, CRUD operations, and plugin server in provider module (docs/architecture/resources/README.md)
4. Add provider integration tests following docs/architecture/testing/integration.md patterns (docs/architecture/testing/integration.md)
5. Register provider in language SDKs (Go, Python, Node.js, .NET) and publish to respective package registries (docs/contributing/development.md)

Add a new Language SDK

1. Review multi-language design in docs/architecture/languages.md to understand SDK code generation and plugin communication (docs/architecture/languages.md)
2. Create new language module structure with generated bindings for resource types and plugin protocol (docs/architecture/README.md)
3. Implement language-specific user-facing API (resource registration, stack management, outputs) (docs/contributing/development.md)
4. Add language SDK build targets to Makefile and CI workflow (.github/workflows/ci-build-sdks.yml) (Makefile)
5. Configure package registry publishing in release workflow (.github/workflows/release.yml) and update version management scripts (.github/scripts/update-versions)

Add a new Deployment Execution Feature

1. Review execution engine architecture in docs/architecture/deployment-execution/README.md to understand state management, resource ordering, and callback system (docs/architecture/deployment-execution/README.md)
2. Study state machine design in docs/architecture/deployment-execution/steps.md for understanding update/create/delete/import workflows (docs/architecture/deployment-execution/steps.md)
3. Implement feature in Go engine code (likely in internal/cmd/pulumi-cli or pkg/engine directories) (go.mod)
4. Add integration tests demonstrating feature across multiple resource types (docs/architecture/testing/integration.md)
5. Update Makefile test targets and add CI jobs in .github/workflows/ci-run-test.yml for continuous validation (.github/workflows/ci-run-test.yml)

Optimize Performance or Fix a Bottleneck

1. Profile code using performance debugging guides in docs/debugging/performance.md (docs/debugging/performance.md)
2. Review linting config (.golangci.yml) and code quality standards in CONTRIBUTING.md (CONTRIBUTING.md)
3. Implement optimization in relevant module (SDK or engine code referenced in go.mod) (go.mod)
4. Add performance regression test to .github/workflows/ci-performance-gate.yml to prevent future regressions (.github/workflows/ci-performance-gate.yml)
5. Document change in changelog/pending/ with YAML file following changelog/config.yaml format (changelog/config.yaml)

• Go — Primary language for CLI, execution engine, and plugin system; enables cross-platform binary distribution and high performance
• gRPC + Protocol Buffers — Plugin communication protocol enabling language-agnostic resource providers; efficient serialization and type safety
• Multiple Language SDKs (Python, Node.js, .NET) — Infrastructure definitions declarable in familiar languages; generated from resource schemas for consistency
• GitHub Actions — Multi-stage CI/CD: linting, testing, binary builds, and multi-registry SDK publishing
• Docker + Dev Containers — Reproducible development environments reducing setup friction across Linux, macOS, and Windows

• Plugin-based architecture with gRPC communication

  • Why: Enables third-party providers and language-agnostic extensions without core engine modification
  • Consequence: Adds serialization overhead (~10-50ms per plugin call) vs. direct in-process calls; requires plugin lifecycle management

• State file as source of truth (local + remote backends)

  • Why: Enables offline operation, auditability, and explicit drift detection without real-time infrastructure monitoring
  • Consequence: Risk of state diverg

Multi-language SDK synchronization: version bumps in one SDK may break others if gRPC protocol contracts change — CI gates on all languages, so changes must pass all five SDK test suites. Pulumi state format versioning: old state files must remain readable; state serialization changes require migration logic. The plugin protocol (gRPC between CLI and providers) is tightly coupled to the Go engine; provider plugin version mismatches can cause silent failures. Development requires Go 1.25.8+, Python 3.7+, and Node.js 14+ simultaneously to test all paths locally.

• Resource Dependency Graph — Pulumi must compute and respect resource ordering; understanding how the engine builds a DAG and validates dependencies is key to fixing provisioning bugs
• State Serialization & Versioning — Pulumi's state snapshots must remain backward-compatible; contributors need to understand JSON schema versioning and migration to avoid breaking existing stacks
• gRPC Plugin Protocol — Resource providers communicate with the Pulumi CLI via gRPC; any provider integration work requires understanding this contract between Go engine and language bindings
• Language Runtime Bindings (FFI & Code Generation) — Each SDK (Python, TypeScript, C#, Go) wraps the Go core via language-specific bindings; understanding how code generation maps provider schemas to idiomatic language APIs is crucial for SDK improvements
• Stack & Config Management — Pulumi stacks isolate state and allow multiple environments; understanding how config is encrypted and merged with secrets is essential for security and multi-tenant features
• Automation API — Pulumi can be embedded in applications via Automation API; this is a higher-level abstraction over the CLI that contributors should understand for programmatic infrastructure provisioning
• Provider Resource Diffing & Update Plans — The preview phase computes which resources will be created/updated/deleted by diffing desired state against actual state; bugs in diffing logic cause incorrect plans

• hashicorp/terraform — Direct alternative using HCL DSL instead of general programming languages; both manage cloud resources declaratively but Pulumi focuses on language-native approach
• aws/aws-cdk — Similar multi-language IaC using Python, TypeScript, Go, C#; AWS-specific but shares architectural philosophy of generating CloudFormation from code
• pulumi/pulumi-aws — Official AWS resource provider for Pulumi; demonstrates the plugin protocol in practice and is a canonical example of extending Pulumi
• pulumi/pulumi-kubernetes — Official Kubernetes provider for Pulumi; critical ecosystem component for users deploying to K8s clusters
• grpc/grpc — Underlying RPC protocol powering the Pulumi plugin system; understanding gRPC is essential for building custom providers

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for devcontainer setup and validate Go version compatibility

The repo has a .devcontainer/Dockerfile and .devcontainer/devcontainer.json but lacks automated tests to ensure the dev environment works correctly. Given the repo uses Go 1.25.8 (in docs/go.mod) and supports multiple SDKs (Python, Node, Go, C#), devcontainer validation tests would prevent breakage when dependencies are updated. New contributors could add CI workflow to build and test the devcontainer image.

• [ ] Create .github/workflows/ci-devcontainer.yml that builds the devcontainer image
• [ ] Add smoke tests in the workflow to verify Go, Node, Python versions match .mise.toml
• [ ] Test that pulumi CLI can be invoked successfully inside the built container
• [ ] Document test execution in CONTRIBUTING.md

Add linting rules for changelog entries and automate changelog validation in CI

The repo has a changelog/pending directory with YAML files (evidenced by the example file with dashes and double-hyphens in names), but there's no visible validation that these entries follow the required schema defined in changelog/config.yaml. New contributors could add a pre-commit hook and CI check to validate YAML structure, required fields, and naming conventions.

• [ ] Review changelog/config.yaml to document required fields for pending entries
• [ ] Create a Go utility in .github/scripts that validates all .yaml files in changelog/pending/
• [ ] Add validation step to .github/workflows/ci-lint.yml to run changelog validation
• [ ] Add pre-commit hook documentation to CONTRIBUTING.md for local validation

Create comprehensive test suite for Go SDK version pinning and replace directives

The docs/go.mod shows a replace directive (github.com/pulumi/pulumi/sdk/v3 => ../../sdk) but there's no visible test coverage for how replace directives behave across the monorepo's multiple Go modules. This is critical for preventing dependency resolution issues when contributors add new Go packages. New contributors could add tests validating SDK version consistency.

• [ ] Create cmd/pulumi/test_go_modules_test.go or similar to validate all go.mod files use matching SDK versions
• [ ] Add test to verify replace directives correctly resolve when building from root and subdirectories
• [ ] Test that 'go mod tidy' and 'go mod verify' pass for all modules listed in Makefile targets
• [ ] Add test documentation to CONTRIBUTING.md's 'Testing' section

• Add integration tests for the TypeScript SDK's resource diffing logic in sdk/nodejs; file structure suggests tests exist but coverage may have gaps given TypeScript's 1.8MB footprint.
• Improve error messages in sdk/v3's plugin protocol layer when a provider doesn't implement a required RPC method; currently may timeout instead of failing clearly.
• Document the state file migration path for sdk/v3 in docs/ or CONTRIBUTING.md; the presence of version scripts suggests this is complex but not well-explained for contributors.

The Pulumi repository demonstrates a mature infrastructure with CI/CD automation and multi-language support. However, several security considerations require attention: (1) The complex GitHub Actions workflow ecosystem presents a significant supply chain attack surface that should be systematically audited, (2) Credential

• Medium · Outdated Go Version in Module — go.mod (docs module). The go.mod file specifies Go 1.25.8, which appears to be a future or incorrect version number. This may indicate outdated or misconfigured build dependencies. Current stable Go versions are in the 1.2x range. This could lead to using an unsupported or non-existent runtime version. Fix: Update to a currently supported Go version (e.g., 1.21 or 1.22). Verify the Go version constraint matches the project's actual requirements and CI/CD configuration.
• Low · Potential Secrets in Environment Templates — .envrc.template. The file '.envrc.template' exists in the repository. While templates themselves are not secrets, they may encourage storing sensitive data in .envrc files which could be accidentally committed if proper gitignore rules are misconfigured. Fix: Ensure .envrc is in .gitignore, document that environment files should never be committed, and use a secrets management system for sensitive credentials instead of environment files.
• Medium · Multiple Workflow Files with Potential Release/Signing Credentials — .github/workflows/*.yml (especially release.yml, sign.yml, on-release.yml). The repository contains multiple GitHub Actions workflows related to releases, signing, and publishing (release.yml, sign.yml, release-homebrew-tap.yml, etc.). These workflows may handle credentials and signing keys. If not properly secured, they could expose credentials through logs or artifacts. Fix: Audit all workflow files to ensure: (1) Secrets are never logged or output, (2) Use GitHub's OIDC token provider instead of long-lived credentials, (3) Limit workflow permissions to minimum required, (4) Audit access to workflow secrets regularly.
• Low · Public Release Key File — .github/workflows/release.pub. The file '.github/workflows/release.pub' appears to be a public key file stored in version control. While public keys are intended to be public, storing them in workflows could indicate inadequate key management practices. Fix: Verify this is indeed a public key (not a private key). Consider storing it in a more appropriate location or using GitHub's secrets for key distribution. Ensure the corresponding private key is never committed and is properly managed.
• Low · Docker Image Build Without Explicit Security Scanning — .devcontainer/Dockerfile, docker/. The presence of .devcontainer/Dockerfile and docker/ directory suggests Docker images are built, but the file structure provided doesn't show evidence of automated security scanning (e.g., Trivy, Snyk) in the build pipeline. Fix: Implement automated Docker image scanning in CI/CD pipelines. Use tools like Trivy or Snyk to scan images for vulnerabilities before publishing. Establish a baseline of allowed vulnerabilities based on severity.
• Low · Third-party Dependency Without Version Pinning Verification — go.mod - github.com/santhosh-tekuri/jsonschema/v5. The go.mod shows a dependency on 'github.com/santhosh-tekuri/jsonschema/v5 v5.0.0' which is relatively new. While the version is specified, there's no evidence of vulnerability scanning for Go dependencies in the provided file structure. Fix: Implement dependency vulnerability scanning using 'go list -json -m all | nancy sleuth' or similar tools. Consider using GitHub Dependabot for automated dependency monitoring and update PRs.
• Medium · Complex Build and Release Workflow Attack Surface — .github/workflows/. The repository has an extensive set of GitHub Actions workflows (40+ files visible) with various automation tasks. Complex workflows increase the attack surface for supply chain attacks, credential exposure, and misconfiguration vulnerabilities. Fix: Conduct a comprehensive security audit of all workflows. Implement: (1) Workflow approval requirements for sensitive operations, (2) Environment-specific protections, (3) Audit logging of workflow executions, (4) Code review for workflow changes, (5) Least privilege principles for workflow permissions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.