docs: gitops with api

Author: tianzhou

content/docs/_layout.md

@@ -139,13 +139,23 @@ expand_section_list: ['Self-host']
 
 ### [Overview](/vcs-integration/overview)
 
-### [Add Git Provider](/vcs-integration/add-git-provider)
+### Simple GitOps
 
-### [Add GitOps Connector in Project](/vcs-integration/add-gitops-connector)
+#### [Overview](/vcs-integration/simple/overview)
 
-### [Create Migration Files](/vcs-integration/create-migration-files)
+#### [Add Git Provider](/vcs-integration/add-git-provider)
 
-### [Troubleshoot 🐞](/vcs-integration/troubleshoot)
+#### [Add GitOps Connector in Project](/vcs-integration/add-gitops-connector)
+
+#### [Create Migration Files](/vcs-integration/create-migration-files)
+
+#### [Troubleshoot 🐞](/vcs-integration/troubleshoot)
+
+### Custom GitOps
+
+#### [Overview](/vcs-integration/custom/overview)
+
+#### [Release](/vcs-integration/custom/release)
 
 ## SQL Editor
 

content/docs/vcs-integration/custom/overview.md

@@ -0,0 +1,7 @@
+---
+title: Custom GitOps
+---
+
+If the built-in [simple GitOps](/docs/vcs-integration/simple/overview/) is not sufficient, you can opt to [Bytebase API](/docs/api/overview/) to fully customize the GitOps workflow to integrate with your CI pipeline.
+
+<TutorialBlock url="/docs/tutorials/github-ci/" title="Automating Database Schema Change workflow Using GitHub Actions" />

content/docs/vcs-integration/custom/release.md

@@ -0,0 +1,15 @@
+---
+title: Release
+---
+
+A `release` is a deployable unit that encapsulates a set of SQL statements.
+
+You can think of a `release` as a collection of SQL statements layered on top of a scratch Docker image.
+
+In your CI/CD pipeline, a Docker image is built from the source code and sent to the CD system for deployment. Similarly, your CI pipeline creates a `release` by invoking the Bytebase API. Once built, the `release` can be deployed to the database either via the Bytebase UI or through the Bytebase API.
+
+<HintBlock type="info">
+
+Like a Docker image, a `release` is immutable after it is created.
+
+</HintBlock>

content/docs/vcs-integration/overview.md

@@ -1,42 +1,16 @@
 ---
-title: GitOps with VCS Integration
+title: GitOps
 ---
 
-## Built-in GitOps
+Bytebase offers a database-as-code workflow, enabling you to manage database changes directly through your version control system (VCS).
 
-### Prerequisites
+Bytebase provides two GitOps workflows:
 
-- Configure [External URL](/docs/get-started/install/external-url).
-- VCS and Bytebase are network reachable from each other.
-  - VCS needs to push webhook to Bytebase.
-  - Bytebase needs to fetch file content from VCS.
-
-### Workflow
-
-![gitops-workflow](/content/docs/vcs-integration/overview/gitops-workflow.webp)
-
-The built-in Bytebase GitOps workflow is **opinionated** for the typical use case:
-
-- It imposes a [naming convention on the migration file](/docs/vcs-integration/create-migration-files/).
-- It only creates Bytebase rollout issue when the migration file is **merged** into the target branch.
-  Under the hood, it creates a webhook in the linked repository to observe the merge event.
-- If you have successfully rolled out the issue and you want to make further change based on that migration file, you need to create a new migration file instead of editing the original one inline.
+- [Simple GitOps](/docs/vcs-integration/simple/overview): Opinionated and restricted for the simple use case.
+- [Custom GitOps](/docs/vcs-integration/custom/overview): Fully customizable via the Bytebase API.
 
 <HintBlock type="info">
 
-You can check this [demo issue](https://demo.bytebase.com/projects/gitops-project/issues/106) to see what it looks like after the setup. This issue is created by Bytebase after the [PR is merged](https://github.com/s-bytebase/hr-sample/pull/17).
+If you manage database changes for multiple teams or have any branching strategy beyond the most basic, you will be likely need the [Custom GitOps](/docs/vcs-integration/custom/overview) workflow.
 
 </HintBlock>
-
-The built-in GitOps setup contains 3 steps:
-
-1. [Add Git Provider](/docs/vcs-integration/add-git-provider)
-1. [Add GitOps Connector in Project](/docs/vcs-integration/add-gitops-connector)
-1. [Create Migration Files](/docs/vcs-integration/create-migration-files)
-
-## Custom GitOps with API
-
-If the built-in workflow is not suitable, you can opt to [Bytebase API](/docs/api/overview/) to fully customize the GitOps workflow to
-integrate with your CI pipeline.
-
-<TutorialBlock url="/docs/tutorials/github-ci/" title="Automating Database Schema Change workflow Using GitHub Actions" />

content/docs/vcs-integration/simple/overview.md

@@ -0,0 +1,26 @@
+---
+title: Simple GitOps
+---
+
+Bytebase provides a built-in GitOps workflow out of the box.
+
+![gitops-workflow](/content/docs/vcs-integration/overview/gitops-workflow.webp)
+
+This GitOps workflow is opinionated for the simple use case:
+
+- It imposes a [naming convention on the migration file](/docs/vcs-integration/create-migration-files/).
+- It only creates Bytebase rollout issue when the migration file is **merged** into the target branch.
+  Under the hood, it creates a webhook in the linked repository to observe the merge event.
+- If you have successfully rolled out the issue and you want to make further change based on that migration file, you need to create a new migration file instead of editing the original one inline.
+
+<HintBlock type="info">
+
+You can check this [demo issue](https://demo.bytebase.com/projects/gitops-project/issues/106) to see what it looks like after the setup. This issue is created by Bytebase after the [PR is merged](https://github.com/s-bytebase/hr-sample/pull/17).
+
+</HintBlock>
+
+The simple GitOps setup contains 3 steps:
+
+1. [Add Git Provider](/docs/vcs-integration/add-git-provider)
+1. [Add GitOps Connector in Project](/docs/vcs-integration/add-gitops-connector)
+1. [Create Migration Files](/docs/vcs-integration/create-migration-files)