docs: add pgfence migration safety check to CI/CD workflow

[flvmnt]

Summary

• Adds a new docs page under Cloud CI/CD (docs/docs/cloud-ci-cd/migration-safety-checks.mdx) showing how to integrate pgfence as a pre-deployment migration safety check
• Includes a full GitHub Actions workflow example that runs npx @flvmnt/pgfence analyze --ci on Hasura migration SQL files before applying them
• Covers risk threshold configuration, JSON output, and Hasura-specific migration path patterns

Context

Hasura migrations are standard Postgres SQL files. Certain DDL statements (non-concurrent CREATE INDEX, ALTER COLUMN TYPE, ADD CONSTRAINT ... FOREIGN KEY without NOT VALID) acquire aggressive locks that can cause downtime on production tables. The existing migration best practices page already recommends breaking down large migrations to avoid locking issues.

pgfence (npm, GitHub) is an open-source Postgres migration safety CLI that detects these patterns statically and provides safe rewrite recipes. Adding it as a CI step catches dangerous migrations before they reach production.

This complements the existing GitHub integration and regression testing docs by covering SQL-level safety analysis.

Test plan

• Verify the new page renders correctly in the Docusaurus dev server
• Confirm sidebar ordering (sidebar_position: 50) places the page between GitHub Integration and Regression Tests
• Validate all internal doc links resolve correctly
• Test the example npx command against a sample Hasura migrations directory

[Copilot]

Pull request overview

This pull request adds comprehensive documentation for integrating pgfence, an open-source PostgreSQL migration safety analysis tool, into Hasura CI/CD pipelines. The documentation provides practical guidance for preventing production downtime caused by dangerous migration patterns that acquire aggressive database locks.

Changes:

• New documentation page explaining how to use pgfence to detect unsafe PostgreSQL migration patterns
• Complete GitHub Actions workflow examples showing pgfence integration before migration deployment
• Risk assessment table covering common dangerous patterns like non-concurrent index creation and unsafe column type changes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This documentation page is missing the ProductBadge component that is consistently included in all other pages in the cloud-ci-cd section. Add the import statement and ProductBadge component after the main heading to match the pattern used in other files like github-integration.mdx, preview-apps.mdx, and regression-tests.mdx.

Suggested change

	# Migration Safety Checks
	import { ProductBadge } from '@site/src/components/ProductBadge';
	# Migration Safety Checks
	<ProductBadge product="cloud-ci-cd" />

[Copilot]

Both of these example commands rely on npx --yes @flvmnt/pgfence analyze ... which pulls and runs the @flvmnt/pgfence npm package in CI without version pinning or integrity checks, creating a supply chain risk. If the npm package is ever compromised, attackers could execute arbitrary code in your CI runner with access to repository contents and any injected secrets. To harden this pattern, pin @flvmnt/pgfence to a specific immutable version and add integrity verification rather than executing an unpinned package via npx in production CI pipelines.

[Copilot]

The recommended npx --yes @flvmnt/pgfence analyze ... step downloads and executes a third-party npm package on every CI run without pinning it to a specific immutable version or verifying integrity, which creates a supply chain risk. If the @flvmnt/pgfence package or its npm distribution is compromised, attackers could execute arbitrary code in your GitHub Actions runner with access to the repository and default secrets (e.g., GITHUB_TOKEN). To reduce this risk, pin @flvmnt/pgfence to a specific trusted version and/or use integrity verification mechanisms rather than invoking an unpinned package via npx in CI.

[Copilot]

In this full workflow example, the Check migration safety step uses npx --yes @flvmnt/pgfence analyze ... to fetch and run a third-party npm package on each CI execution without version pinning or integrity checks, exposing the pipeline to supply chain compromise. A malicious or hijacked @flvmnt/pgfence release could run arbitrary code in the GitHub Actions environment, potentially exfiltrating repository data or abusing the default GITHUB_TOKEN. Consider pinning @flvmnt/pgfence to a specific immutable version and adding integrity verification instead of running an unpinned package via npx in CI.

[Copilot]

The Check migration safety step here again uses npx --yes @flvmnt/pgfence analyze ... without pinning a specific version or verifying package integrity, which is a supply chain risk in CI. If the npm package @flvmnt/pgfence is compromised, an attacker could execute arbitrary code in the workflow environment with access to repository contents and default GitHub Actions secrets. Prefer pinning @flvmnt/pgfence to a known-good version and employing integrity checks instead of invoking an unpinned package directly via npx.

[Copilot]

This example uses npx --yes @flvmnt/pgfence analyze --output json ... which downloads and executes the @flvmnt/pgfence npm package on each CI run without a fixed version or integrity verification, introducing a supply chain attack surface. A compromised package release could run arbitrary code within the GitHub Actions runner and access repository data or GitHub-provided secrets. Mitigate this by pinning @flvmnt/pgfence to a specific immutable version and/or validating the package integrity instead of calling an unpinned package via npx.

[flvmnt]

Addressed feedback: added ProductBadge to match section conventions, pinned pgfence version in all examples, removed hidden Unicode characters.

[flvmnt]

Pushed fixes: stripped hidden Unicode characters flagged by GitHub, verified all npx commands pinned to @0.2.1 with --yes.

[Moses-main]

Hi team,

I'll add the pgfence migration safety check to CI/CD. Documentation/improvement!

Let me know!