Add Custom VCS docs and launch blog post

[fallimic]

Proposed changes

Adds documentation and a launch blog post for Custom VCS — a new Pulumi Cloud integration that connects any Git-based version control system (self-hosted or third-party) to Pulumi Deployments using webhooks and ESC-managed credentials.

Unreleased product version (optional)

Related issues (optional)

Feature implemented in pulumi/pulumi-service (PR #41027 and related backend PRs)

[claude]

Docs Review — PR #18524

Scope: Blog post (content/blog/connect-any-git-server-to-pulumi-deployments-with-custom-vcs/index.md), docs page (content/docs/version-control/custom-vcs.md), version control index updates (content/docs/version-control/_index.md), images, and SVG logo.

Overall this is a well-structured PR. The blog post is clear and concise, the docs page is thorough with good use of tables and shortcodes, and the _index.md updates integrate the new feature cleanly. A few items to address:

---

Issues

1. Social media copy is empty (blog index.md, lines 18–20)

The social: block has blank twitter, linkedin, and bluesky values. Without copy, the post won't be auto-promoted on social media when merged.

social:
    twitter: "Custom VCS integrations are here — connect any Git server to Pulumi Deployments with webhook-driven push-to-deploy and ESC-managed credentials."
    linkedin: ""
    bluesky: ""

(Suggestion is illustrative — please fill in platform-appropriate copy before merging.)

2. static/logos/tech/git.svg missing trailing newline (line 1)

The SVG file doesn't end with a newline character. New files should end with a trailing newline.

---

Publishing readiness checklist (blog)

• social: block present with copy for twitter, linkedin, bluesky — fields are blank, needs copy
• meta_image set and not empty (meta.png, 225 KB, 1200×628)
• meta_image uses current Pulumi logo
• <!--more--> break present after intro
• Author profile exists (data/team/team/michael-fallihee.toml)
• All internal links resolve (/docs/deployments/deployments/, /docs/esc/, /docs/version-control/github-app/, /docs/version-control/gitlab/, /docs/version-control/azure-devops-integration/, /docs/version-control/custom-vcs/, /docs/ai/, /docs/deployments/deployments/using/triggers/)
• Code examples correct with language specifiers (yaml, json, text)
• No animated GIFs used as meta_image
• feature.png dimensions correct (1884×1256)
• Title ≤60 chars (exactly 60)
• Meta description ≤160 chars (154)

Docs page notes

• Headings follow sentence case ✓
• Ordered lists use 1. for all items ✓
• Shortcodes use correct {{% %}} syntax for notes ✓
• Menu weight (5) places Custom VCS after Azure DevOps (4) in the sidebar ✓
• Comparison table is well-structured and more detailed than the blog version ✓
• Troubleshooting table covers the key failure modes ✓
• Doc meta description is 122 chars (within limit) ✓

---

Mention @claude in a comment if you'd like additional reviews or automated fixes.

[github-actions]

Social Media Review

content/blog/connect-any-git-server-to-pulumi-deployments-with-custom-vcs/index.md

X — missing

LinkedIn — missing

Bluesky — missing

No social copy found for any platform. Suggested copy below — all three passed critique.

---

Suggested copy

X (222/255 chars):

Teams running self-hosted Git servers have been locked out of push-to-deploy. Every stack needed its own credentials, and there was no webhook to trigger on push.

Custom VCS changes that. Here's what the setup looks like.

LinkedIn (586/2950 chars):

If your team uses GitHub, GitLab, or Azure DevOps, Pulumi Deployments connects to them natively. If you run anything else, the only path to push-to-deploy was awkward: store credentials in each stack's deployment settings individually, trigger deployments by hand or through a separate CI pipeline.

Every stack that shared a repository had to duplicate that work.

We built a new integration type that works at the org level. It uses Pulumi ESC for credentials, so multiple stacks can share one configuration — and it fires on push via webhooks.

Here's what the full setup looks like.

Bluesky (259/300 chars):

If your team runs a Git server that isn't GitHub, GitLab, or Azure DevOps, Pulumi Deployments had no native integration for you — just raw credential config per stack and no way to trigger on push.

Custom VCS closes that. Here's what it takes to connect one.

---

To apply these suggestions, comment: @claude please update the social posts in the frontmatter with the suggested copy from the social media review above

To re-run the social media review after updates, comment: /social-review

[pulumi-bot]

Your site preview for commit bbae8f3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18524-bbae8f3c.s3-website.us-west-2.amazonaws.com

[pulumi-bot]

Lighthouse Performance Report

Commit: bbae8f3 | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🟡 83	3.0s	3.5s	170ms	0.014	3.0s
Homepage	Desktop	🟢 97	0.7s	1.0s	16ms	0.077	1.0s
Install Pulumi	Mobile	🔴 39	4.4s	5.9s	249ms	0.432	6.8s
Install Pulumi	Desktop	🟢 95	1.0s	1.4s	17ms	0.020	1.0s
AWS Get Started	Mobile	🟡 60	4.2s	5.6s	177ms	0.093	6.5s
AWS Get Started	Desktop	🟢 90	1.0s	1.3s	12ms	0.036	2.4s

[github-actions]

Social Media Review

content/blog/connect-any-git-server-to-pulumi-deployments-with-custom-vcs/index.md

X — missing

LinkedIn — missing

Bluesky — missing

No social copy found for any platform. Suggested copy below — all three passed critique.

---

Suggested copy

X (240/255 chars):

Teams running self-hosted Git or Mercurial have had one path to Pulumi Deployments: configure credentials per stack, trigger deployments manually, and work without org-level sharing.

We built Custom VCS to change that. Here's how it works.

LinkedIn (665/2950 chars):

If your team runs a self-hosted Git server or Mercurial, Pulumi Deployments has given you one integration path: embed credentials directly in each stack's deployment settings and trigger deploys manually or through a separate CI pipeline.

It works, but every new stack means repeating the same credential setup. There is no push-to-deploy, no webhook automation, and no shared configuration at the org level.

We built Custom VCS to change that. It works with any Git or Mercurial server, but the design trade-offs are worth understanding before you reach for it over a native integration.

Here's what it supports, what it doesn't, and how to connect your server.

Bluesky (288/300 chars):

Teams using self-hosted Git or Mercurial have had no push-to-deploy with Pulumi Deployments. Credentials had to be configured per stack and every deployment had to be triggered manually.

We shipped Custom VCS to fix that. Here's what changes and what still requires a native integration.

---

To apply these suggestions, comment: @claude please update the social posts in the frontmatter with the suggested copy from the social media review above

To re-run the social media review after updates, comment: /social-review

[github-actions]

Social Media Review

content/blog/connect-any-git-server-to-pulumi-deployments-with-custom-vcs/index.md

X — missing

LinkedIn — missing

Bluesky — missing

No social copy was found for any platform. Suggested copy below.

---

Suggested copy

X (227/255 chars):

Teams on self-hosted Git or Mercurial had to configure Pulumi Deployments credentials per stack by hand, with no push-to-deploy and no shared credentials.

We added Custom VCS. Here's how to connect any Git or Mercurial server.

LinkedIn (580/2950 chars):

GitHub, GitLab, and Azure DevOps have native Pulumi Deployments integrations that handle OAuth, webhook configuration, and push-to-deploy automatically. Self-hosted Git servers and Mercurial had none of that.

The only option was the raw git approach: embed credentials directly in each stack's deployment settings, with no webhook automation and every deployment triggered by hand.

Custom VCS is a new Pulumi Cloud integration that extends the same deployment automation to any Git or Mercurial server.

Here's how to set it up and where it differs from the native integrations.

Bluesky (274/300 chars):

Self-hosted Git servers and Mercurial have been outside Pulumi Deployments' native integrations. The only option was embedding credentials per stack by hand, with no push-to-deploy automation.

We added Custom VCS to close that gap. Here's how it works and what it supports.

---

To apply these suggestions, comment: @claude please update the social posts in the frontmatter with the suggested copy from the social media review above

To re-run the social media review after updates, comment: /social-review

[claude]

Docs Review

PR adds documentation and a launch blog post for Custom VCS -- a new Pulumi Cloud integration for connecting any Git or Mercurial VCS to Pulumi Deployments. Overall this is well-written, clearly structured, and technically thorough. A few items to address before merging:

---

Issues

1. Blog URL slug does not match title (SEO)

The blog title is Connect Any Git or Mercurial Repo to Pulumi with Custom VCS but the directory slug is connect-any-git-server-to-pulumi-deployments-with-custom-vcs. The slug says "git-server" and omits "Mercurial," which the title explicitly calls out as a supported VCS type. Since Mercurial support is a key differentiator of this feature, the slug should reflect it for search discoverability. Consider renaming the blog directory to match the title more closely.

2. Social media copy is empty (content/blog/.../index.md, lines 18-20)

The social: block is present but all three platforms (twitter, linkedin, bluesky) are blank. Without copy, this post will not be promoted on social media when merged. Please add social media copy before merging or confirm this is intentional.

3. git.svg missing trailing newline (static/logos/tech/git.svg)

The SVG file is missing a trailing newline. Per the review criteria, all new files should end with a newline.

4. Terminology inconsistency in troubleshooting table (content/docs/version-control/custom-vcs.md, line 195)

The troubleshooting table says "deploy on push" but the Deployment settings table on line 156 calls it "Push to deploy". These should use the same label to avoid confusion.

5. Blog post has no CTA

The blog ends with a "Learn more" links section, which is fine, but there is no call-to-action button using the blog/cta-button shortcode. For a feature launch post, consider adding a CTA that links to the setup page or to Pulumi Cloud directly.

---

Minor / Optional

• First mention of Mercurial not hyperlinked (blog index.md, line 24): The review criteria says first mentions of tools/technologies should be linked. Mercurial could be linked on first mention since it is less commonly known than Git.
• Blog date (index.md, line 3): The publish date is 2026-04-14, which is yesterday. Confirm this is the intended publish date.

---

What looks good

• Both the blog post and docs page are well-structured and clearly written.
• All internal links verified and resolve correctly.
• Author profile (michael-fallihee) exists with avatar image.
• meta_image is set, non-empty, and uses current Pulumi branding/logo.
• <!--more--> break is properly placed after the opening paragraph.
• Blog title is 59 characters (under 60-char limit).
• Meta descriptions are appropriate length (blog: 153 chars, docs: 129 chars, both under 160).
• Heading case is correct throughout (Title Case for H1, sentence case for H2+).
• No prohibited language found.
• ESC credential YAML examples and webhook JSON payload look correct and realistic.
• Image file sizes are reasonable (feature.png: 30KB, meta.png: 224KB).
• Menu weight (5) positions Custom VCS correctly after native integrations in the sidebar.
• The _index.md updates for the version control landing page correctly add the new card entry.
• schema_type: auto is set per blog conventions.
• The comparison tables in both blog and docs are helpful for setting expectations vs native integrations.

---

Publishing readiness checklist (blog)

• social: block present with copy for twitter, linkedin, bluesky -- empty, needs copy
• meta_image set and not empty
• meta_image uses current Pulumi logos
• <!--more--> break present after intro
• Author profile exists with avatar
• All links resolve
• Code examples correct with language specifiers
• No animated GIFs used as meta_image
• Images have appropriate format and size
• Title is 59 chars (under 60-char limit)

---

Mention me (@claude) if you would like additional reviews or help fixing any of these items.

[CamSoper]

Reviewed the docs and blog for the Custom VCS launch. Verified the webhook URL, headers (X-Generic-VCS-Integration-ID, X-Generic-VCS-Signature), HMAC v1= signing scheme, payload fields, and ESC credential keys against pulumi/pulumi-service (cmd/service/vcs/generic/webhook.go, source_context.go). Internal cross-references and the #push-to-deploy anchor all resolve. Style and structure are clean.

LGTM!

[CamSoper]

@fallimic still WIP? Waiting on that other review?

[fallimic]

Waiting o

@fallimic still WIP? Waiting on that other review?

Waiting on some other PRs to land before launch. Will get this branch update again.