docs: reorganize GitOps workflow documentation (#877)

- Create new "Develop" page with filename requirements
- Move CI platform integrations to "Release" page
- Simplify overview with focus on core workflow
- Update navigation structure in docs.json

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <[email protected]>

Author: d-bytebase

mintlify/docs.json

@@ -128,6 +128,7 @@
             "group": "GitOps Workflow",
             "pages": [
               "gitops/overview",
+              "gitops/develop",
               "gitops/sql-review-ci",
               "gitops/release"
             ]

mintlify/gitops/develop.mdx

@@ -0,0 +1,42 @@
+---
+title: Develop
+---
+
+## Filename Requirements
+
+To ensure proper version control and execution, your SQL migration filenames must follow a specific structure. Each filename consists of three main parts: a **Version**, a **Description**, and an optional **Change Type Suffix**.
+
+`<Version>_<Description>_<Suffix>.sql`
+
+### Versioning Format
+
+Bytebase supports both semantic versioning and simple timestamp-based versions. The version number is crucial for ordering migrations correctly.
+
+The version must begin with a number. A `v` or `V` prefix is optional.
+
+**Valid Version Examples:**
+
+- `202501150900_add_user_table.sql`
+- `v1.2.3_description.sql`
+- `V2_add_users_table.sql`
+- `1.0_initial_schema.sql`
+
+### Change Type Suffixes
+
+You can add a suffix to the filename to specify the change type. **If the suffix is omitted, the file will be treated as the default `DDL` type.** The suffix is added to the end of the filename, just before the `.sql` extension.
+
+- **DDL (Default)**
+
+  - Used for standard schema changes (Data Definition Language). This is the default type used when no suffix is present.
+  - **Example**: `v1.0_create_table.sql`
+
+- **DML**
+
+  - Used for data manipulations (Data Manipulation Language).
+  - Add the `_dml` suffix.
+  - **Example**: `v1.0_insert_data_dml.sql`
+
+- **Ghost**
+  - Used for schema changes performed using the `gh-ost` tool.
+  - Add the `_ghost` suffix.
+  - **Example**: `v1.0_alter_table_ghost.sql`

mintlify/gitops/overview.mdx

@@ -4,7 +4,7 @@ title: Overview
 
 Bytebase offers a database-as-code workflow, enabling you to manage database changes directly through your version control system (VCS).
 
-Bytebase GitOps workflow is built upon the [Bytebase API](/integrations/api/overview). It provides the ultimate flexibility to customize the GitOps workflow to integrate with your CI/CD pipeline.
+Bytebase provides pre-built actions for popular CI/CD platforms. For custom requirements, you can build your own pipeline using the [Bytebase API](/integrations/api/overview).
 
 ## Capabilities
 
@@ -18,13 +18,6 @@ Bytebase GitOps integration provides two core capabilities:
 - **Progressive deployments** - Automated rollout across environments (test → staging → production)
 - **Multi-database support** - Apply changes across multiple databases with batch operations
 
-### SQL Review
-
-- **Automated validation** - Automatically check SQL files against configurable review policies
-- **Quality and compliance checks** - Validate for performance issues, security concerns, and best practices
-- **PR integration** - Review results posted directly as pull request comments
-- **Merge protection** - Block merges when critical issues are detected
-- **Database-specific rules** - Tailored validation for different database engines
 
 ## GitOps Workflow
 
@@ -62,106 +55,3 @@ The release follows your configured deployment pipeline:
 - Each deployment is tracked with timing and status
 
 **Important**: When deploying a release, Bytebase automatically detects which migrations have already been applied to the target database and skips them. This ensures safe re-deployment and allows the same release to be deployed multiple times without errors.
-
-## Requirements
-
-## Filename Requirements
-
-To ensure proper version control and execution, your SQL migration filenames must follow a specific structure. Each filename consists of three main parts: a **Version**, a **Description**, and an optional **Change Type Suffix**.
-
-`<Version>_<Description>_<Suffix>.sql`
-
-### Versioning Format
-
-Bytebase supports both semantic versioning and simple timestamp-based versions. The version number is crucial for ordering migrations correctly.
-
-The version must begin with a number. A `v` or `V` prefix is optional.
-
-**Valid Version Examples:**
-
-- `202501150900_add_user_table.sql`
-- `v1.2.3_description.sql`
-- `V2_add_users_table.sql`
-- `1.0_initial_schema.sql`
-
-### Change Type Suffixes
-
-You can add a suffix to the filename to specify the change type. **If the suffix is omitted, the file will be treated as the default `DDL` type.** The suffix is added to the end of the filename, just before the `.sql` extension.
-
-- **DDL (Default)**
-
-  - Used for standard schema changes (Data Definition Language). This is the default type used when no suffix is present.
-  - **Example**: `v1.0_create_table.sql`
-
-- **DML**
-
-  - Used for data manipulations (Data Manipulation Language).
-  - Add the `_dml` suffix.
-  - **Example**: `v1.0_insert_data_dml.sql`
-
-- **Ghost**
-  - Used for schema changes performed using the `gh-ost` tool.
-  - Add the `_ghost` suffix.
-  - **Example**: `v1.0_alter_table_ghost.sql`
-
-## GitHub Actions
-
-<Card
-  title="Tutorial: Database GitOps with GitHub Actions"
-  icon="graduation-cap"
-  href="/tutorials/gitops-github-workflow/"
-  horizontal
-/>
-
-<Note>
-
-To reach your self-hosted Bytebase from GitHub Actions, you can choose either options:
-
-1. Tunnel GitHub Actions using [Cloudflare Zero Trust](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with [Cloudflare Warp GitHub Actions](https://github.com/marketplace/actions/setup-cloudflare-warp).
-
-1. Use [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).
-
-</Note>
-
-Bytebase provides pre-built [GitHub Actions](https://github.com/marketplace?query=bytebase&type=actions) to ease the GitHub integration.
-
-## Azure DevOps Pipeline
-
-<Card
-  title="Tutorial: Database GitOps with Azure DevOps Pipeline"
-  icon="graduation-cap"
-  href="/tutorials/gitops-azure-devops-workflow/"
-  horizontal
-/>
-
-## GitLab CI
-
-<Card
-  title="Tutorial: Database GitOps with GitLab CI"
-  icon="graduation-cap"
-  href="/tutorials/gitops-gitlab-workflow/"
-  horizontal
-/>
-
-<Note>
-
-If you're using **self-hosted GitLab** in an internal network:
-
-1. You’ll need to [manually load the `bytebase/bytebase-action` image](/tutorials/gitops-gitlab-workflow#use-bytebase-action-in-an-offline-gitlab-runner) into your internal Docker registry.
-
-1. Set the [`clone_url` in GitLab Runner](/tutorials/gitops-gitlab-workflow#resolve-gitlab-clone-redirect-in-internal-network) to avoid redirection to external addresses.
-
-</Note>
-
-## Bitbucket Pipelines
-
-<Card
-  title="Tutorial: Database GitOps with Bitbucket Pipelines"
-  icon="graduation-cap"
-  href="/tutorials/gitops-bitbucket-workflow/"
-  horizontal
-/>
-
-## API
-
-If the pre-built GitHub Actions do not meet your needs or you want to integrate with other VCSs, you can use the [Bytebase API](/integrations/api/overview) to build your own GitOps workflow.

mintlify/gitops/release.mdx

@@ -2,41 +2,67 @@
 title: Release
 ---
 
-A release is an immutable, deployable artifact that contains database changes. It serves as the database equivalent of a Docker image in modern CI/CD pipelines.
+Bytebase integrates with popular CI/CD platforms to automate database releases through GitOps workflows.
 
-## Overview
+## Release Workflow
 
-In Bytebase's GitOps workflow, a release is automatically created when changes are merged to your main branch. It packages all SQL migration files into a single deployable unit that can be progressively rolled out across your database environments.
+When triggered by your CI/CD pipeline, Bytebase automatically creates a **release** - an immutable package containing all your SQL migration files. This release can then be progressively deployed across your database environments (test → staging → production), ensuring consistent and traceable database changes.
 
-## Key Characteristics
+## GitHub Actions
 
-- **Immutable** - Once created, a release cannot be modified, ensuring deployment consistency
-- **Version-controlled** - Each release is tied to a specific VCS commit for full traceability
-- **Environment-agnostic** - The same release can be deployed across test, staging, and production
-- **Auditable** - Complete history of creation, deployment, and rollback operations
-- **Idempotent** - Bytebase automatically detects and skips already applied migrations, preventing duplicate executions
+<Card
+  title="Tutorial: Database GitOps with GitHub Actions"
+  icon="graduation-cap"
+  href="/tutorials/gitops-github-workflow/"
+  horizontal
+/>
 
-## Benefits
+<Note>
 
-### Consistency
+To reach your self-hosted Bytebase from GitHub Actions, you can choose either options:
 
-The same release deployed to test is exactly what gets deployed to production - no manual SQL copying or modification.
+1. Tunnel GitHub Actions using [Cloudflare Zero Trust](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with [Cloudflare Warp GitHub Actions](https://github.com/marketplace/actions/setup-cloudflare-warp).
 
-### Idempotent Deployment
+1. Use [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).
 
-Bytebase tracks which migrations have been applied to each database. When deploying a release:
+</Note>
 
-- Already applied migrations are automatically skipped
-- Only new migrations are executed
-- Safe to re-deploy the same release multiple times
-- No risk of duplicate schema changes or data corruption
+Bytebase provides pre-built [GitHub Actions](https://github.com/marketplace?query=bytebase&type=actions) to ease the GitHub integration.
 
-### Compliance
+## Azure DevOps Pipeline
 
-- Every change is reviewed before release creation
-- Deployment requires appropriate approvals
-- Full audit trail for regulatory requirements
+<Card
+  title="Tutorial: Database GitOps with Azure DevOps Pipeline"
+  icon="graduation-cap"
+  href="/tutorials/gitops-azure-devops-workflow/"
+  horizontal
+/>
 
-### Integration
+## GitLab CI
+
+<Card
+  title="Tutorial: Database GitOps with GitLab CI"
+  icon="graduation-cap"
+  href="/tutorials/gitops-gitlab-workflow/"
+  horizontal
+/>
+
+<Note>
+
+If you're using **self-hosted GitLab** in an internal network:
+
+1. You'll need to [manually load the `bytebase/bytebase-action` image](/tutorials/gitops-gitlab-workflow#use-bytebase-action-in-an-offline-gitlab-runner) into your internal Docker registry.
+
+1. Set the [`clone_url` in GitLab Runner](/tutorials/gitops-gitlab-workflow#resolve-gitlab-clone-redirect-in-internal-network) to avoid redirection to external addresses.
+
+</Note>
+
+## Bitbucket Pipelines
+
+<Card
+  title="Tutorial: Database GitOps with Bitbucket Pipelines"
+  icon="graduation-cap"
+  href="/tutorials/gitops-bitbucket-workflow/"
+  horizontal
+/>
 
-Releases integrate seamlessly with existing CI/CD tools, treating database changes with the same rigor as application deployments.