Trigger on Git merge (#5244)

## What are you changing in this pull request and why?

Docs for beta launch of Trigger on merge:

- new **Merge jobs** page
- update [Deployments
landing](https://docs.getdbt.com/docs/deploy/deployments) page
- update [Jobs landing](https://docs.getdbt.com/docs/deploy/jobs) page
- new section **Treatment of merge jobs** on [Job
scheduler](https://docs.getdbt.com/docs/deploy/job-scheduler) page
- On [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) page:
updated UI labels to match sentence casing; refactored old examples
section a bit since the page is getting long
- new release note

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [x] Needs PM review

Adding or removing sections:
- [x] Update link URLs if needed -- checked, not needed, not referenced
elsewhere
- [x] Add an entry for deleted sections in `website/vercel.json` if
possible -- checked, not needed, not referenced elsewhere
- [x] Run link testing locally with `npm run build` to update the links
that point to deleted pages
- [x] Check if screenshot files need to be deleted -- removed when
screenshot is not referenced elsewhere

website/docs/docs/dbt-versions/release-notes/70-Apr-2024/merge-jobs.md

@@ -0,0 +1,14 @@
+---
+title: "New: Merge jobs"
+description: "April 2024: Native support now available in dbt Cloud to trigger dbt job runs when Git pull requests merge."
+sidebar_label: "New: Merge jobs"
+sidebar_position: 07
+tags: [Apr-2024]
+date: 2024-04-17
+---
+
+# New: Merge jobs <Lifecycle status="beta" />
+
+You can now set up a continuous deployment (CD) workflow for your projects natively in dbt Cloud. You can now access a beta release of [Merge jobs](/docs/deploy/merge-jobs), which is a new [job type](/docs/deploy/jobs), that enables you to trigger dbt job runs as soon as changes (via Git pull requests) merge into production. 
+
+<Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/example-create-merge-job.png" width="90%" title="Example of creating a merge job"/>

website/docs/docs/deploy/ci-jobs.md

@@ -20,15 +20,16 @@ dbt Labs recommends that you create your CI job in a dedicated dbt Cloud [deploy
 
 To make CI job creation easier, many options on the **CI job** page are set to default values that dbt Labs recommends that you use. If you don't want to use the defaults, you can change them.
 
-1. On your deployment environment page, click **Create Job** > **Continuous Integration Job** to create a new CI job. 
+1. On your deployment environment page, click **Create job** > **Continuous integration job** to create a new CI job. 
 
-2. Options in the **Job Description** section:
-    - **Job Name** — Specify the name for this CI job.
+2. Options in the **Job settings** section:
+    - **Job name** — Specify the name for this CI job.
+    - **Description** — Provide a description about the CI job.
     - **Environment** — By default, it’s set to the environment you created the CI job from.
     - **Triggered by pull requests** — By default, it’s enabled. Every time a developer opens up a pull request or pushes a commit to an existing pull request, this job will get triggered to run.
       - **Run on Draft Pull Request** — Enable this option if you want to also trigger the job to run every time a developer opens up a draft pull request or pushes a commit to that draft pull request. 
 
-3. Options in the **Execution Settings** section:
+3. Options in the **Execution settings** section:
     - **Commands** — By default, it includes the `dbt build --select state:modified+` command. This informs dbt Cloud to build only new or changed models and their downstream dependents. Importantly, state comparison can only happen when there is a deferred environment selected to compare state to. Click **Add command** to add more [commands](/docs/deploy/job-commands)  that you want to be invoked when this job runs.
     - **Compare changes against an environment (Deferral)** — By default, it’s set to the **Production** environment if you created one. This option allows dbt Cloud to check the state of the code in the PR against the code running in the deferred environment, so as to only check the modified code, instead of building the full table or the entire DAG.
 
@@ -38,17 +39,23 @@ To make CI job creation easier, many options on the **CI job** page are set to d
 
     - **Generate docs on run** — Enable this option if you want to [generate project docs](/docs/collaborate/build-and-view-your-docs) when this job runs. This option is disabled by default since most teams do not want to test doc generation on every CI check.
 
-  <Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/create-ci-job.png" width="90%" title="Example of CI Job page in dbt Cloud UI"/>
-
-4. (optional) Options in the **Advanced Settings** section: 
-    - **Environment Variables** &mdash; Define [environment variables](/docs/build/environment-variables) to customize the behavior of your project when this CI job runs. You can specify that a CI job is running in a _Staging_ or _CI_ environment by setting an environment variable and modifying your project code to behave differently, depending on the context. It's common for teams to process only a subset of data for CI runs, using environment variables to branch logic in their dbt project code.
-    - **Target Name** &mdash; Define the [target name](/docs/build/custom-target-names). Similar to **Environment Variables**, this option lets you customize the behavior of the project. You can use this option to specify that a CI job is running in a _Staging_ or _CI_ environment by setting the target name and modifying your project code to behave differently, depending on the context. 
-    - **Run Timeout** &mdash; Cancel this CI job if the run time exceeds the timeout value. You can use this option to help ensure that a CI check doesn't consume too much of your warehouse resources.
-    - **dbt Version** &mdash; By default, it’s set to inherit the [dbt version](/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior.
+4. (optional) Options in the **Advanced settings** section: 
+    - **Environment variables** &mdash; Define [environment variables](/docs/build/environment-variables) to customize the behavior of your project when this CI job runs. You can specify that a CI job is running in a _Staging_ or _CI_ environment by setting an environment variable and modifying your project code to behave differently, depending on the context. It's common for teams to process only a subset of data for CI runs, using environment variables to branch logic in their dbt project code.
+    - **Target name** &mdash; Define the [target name](/docs/build/custom-target-names). Similar to **Environment Variables**, this option lets you customize the behavior of the project. You can use this option to specify that a CI job is running in a _Staging_ or _CI_ environment by setting the target name and modifying your project code to behave differently, depending on the context. 
+    - **Run timeout** &mdash; Cancel this CI job if the run time exceeds the timeout value. You can use this option to help ensure that a CI check doesn't consume too much of your warehouse resources.
+    - **dbt version** &mdash; By default, it’s set to inherit the [dbt version](/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior.
     - **Threads** &mdash; By default, it’s set to 4 [threads](/docs/core/connect-data-platform/connection-profiles#understanding-threads). Increase the thread count to increase model execution concurrency.
     - **Run source freshness** &mdash; Enable this option to invoke the `dbt source freshness` command before running this CI job. Refer to [Source freshness](/docs/deploy/source-freshness) for more details.
 
-    <Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/ci-job-adv-settings.png" width="90%" title="Example of Advanced Settings on the CI Job page"/>
+### Examples
+
+- Example of creating a CI job:
+   <Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/create-ci-job.png" title="Example of CI Job page in dbt Cloud UI"/>
+
+- Example of GitHub pull request. The green checkmark means the dbt build and tests were successful. Clicking on the dbt Cloud section navigates you to the relevant CI run in dbt Cloud.
+
+   <Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/example-github-pr.png" title="GitHub pull request example"/>
+
 
 ## Trigger a CI job with the API
 
@@ -70,26 +77,9 @@ If you're not using dbt Cloud’s native Git integration with [GitHub](/docs/cl
       - `non_native_pull_request_id` (for example, BitBucket)
    - Provide the `git_sha` or `git_branch` to target the correct commit or branch to run the job against. 
 
-## Example pull requests
-
-The green checkmark means the dbt build and tests were successful. Clicking on the dbt Cloud section navigates you to the relevant CI run in dbt Cloud.
-
-### GitHub pull request example
-
-<Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/example-github-pr.png" width="70%" title="GitHub pull request example"/>
-
-### GitLab pull request example
-
-<Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/GitLab-Pipeline.png" width="70%" title="GitLab pull request"/>
-
-### Azure DevOps pull request example
-
-<Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/Enabling-CI/ADO CI Check.png" width="70%" title="Azure DevOps pull request"/>
 
 ## Troubleshooting
 
-If you're experiencing any issues, review some of the common questions and answers.
-
 <detailsToggle alt_header="Temporary schemas aren't dropping">
 If your temporary schemas aren't dropping after a PR merges or closes, this typically indicates one of these issues:
 - You have overridden the <code>generate_schema_name</code> macro and it isn't using <code>dbt_cloud_pr_</code> as the prefix.

website/docs/docs/deploy/deployment-overview.md

@@ -43,6 +43,12 @@ Learn how to use dbt Cloud's features to help your team ship timely and quality
     link="/docs/deploy/continuous-integration"
     icon="dbt-bit"/>
 
+<Card
+    title="Merge jobs"
+    body="Set up jobs to run when pull requests are merged in your Git repository."
+    link="/docs/deploy/merge-jobs"
+    icon="dbt-bit"/>
+
 <Card
     title="Job commands"
     body="Configure which dbt commands to execute when running a dbt job."

website/docs/docs/deploy/job-scheduler.md

@@ -57,6 +57,12 @@ When compared to deployment jobs, the scheduler behaves differently when handlin
 - **Will the CI run consume a run slot?** — CI runs don't consume run slots and will never block production runs.
 - **Does this same job have a run already in progress?** — CI runs can execute concurrently (in parallel). CI runs build into unique temporary schemas, and CI checks execute in parallel to help increase team productivity. Teammates never have to wait to get a CI check review.
 
+### Treatment of merge jobs
+When triggered by a _merged_ Git pull request, the scheduler queues a [merge job](/docs/deploy/merge-jobs) to be processed.
+
+- **Will the merge job run consume a run slot?** — Yes, merge jobs do consume run slots.
+- **Does this same job have a run already in progress?** — A merge job can only have one run in progress at a time. If there are multiple runs queued up, the scheduler will enqueue the most recent run and cancel all the other runs. If there is a run in progress, it will wait until the run completes before queuing the next run.
+
 ## Job memory
 
 In dbt Cloud, the setting to provision memory available to a job is defined at the account-level and applies to each job running in the account; the memory limit cannot be customized per job. If a running job reaches its memory limit, the run is terminated with a "memory limit error" message.

website/docs/docs/deploy/jobs.md

@@ -1,23 +1,24 @@
 ---
 title: "Jobs in dbt Cloud"
 sidebar_label: "About Jobs"
-description: "Learn about deploy jobs and continuous integration (CI) jobs in dbt Cloud and what their differences are." 
+description: "Learn about the different job types in dbt Cloud and what their differences are." 
 tags: [scheduler]
 pagination_next: "docs/deploy/deploy-jobs"
 ---
 
-In dbt Cloud, there are two types of jobs: 
+These are the available job types in dbt Cloud: 
 - [Deploy jobs](/docs/deploy/deploy-jobs) — To create and set up triggers for building production data assets
 - [Continuous integration (CI) jobs](/docs/deploy/continuous-integration) — To create and set up triggers for checking code changes
+- [Merge jobs](/docs/deploy/merge-jobs) — To create and set up triggers for merged pull requests
 
-Below is a comparison table that describes how deploy jobs and CI jobs behave:
+Below is a comparison table that describes the behaviors of the different job types:
 
-|  | Deploy Jobs | CI Jobs |
-| --- | --- | --- |
-| Purpose | Builds production data assets. | Builds and tests new code before merging changes into production. |
-| Trigger types | Triggered by a schedule or by API. | Triggered by a commit to a PR or by API. |
-| Destination | Builds into a production database and schema. | Builds into a staging database and ephemeral schema, lived for the lifetime of the PR. |
-| Execution mode | Runs execute sequentially, so as to not have collisions on the underlying DAG. | Runs execute in parallel to promote team velocity. |
-| Efficiency run savings | Detects over-scheduled jobs and cancels unnecessary runs to avoid queue clog. | Cancels existing runs when a newer commit is pushed to avoid redundant work. |
-| State comparison | Only sometimes needs to detect state. | Almost always needs to compare state against the production environment to build on modified code and its dependents. |
-| Job run duration | Limit is 24 hours. | Limit is 24 hours. |
+|  | **Deploy jobs** | **CI jobs** | **Merge jobs** |  
+| --- | --- | --- | --- |
+| Purpose | Builds production data assets. | Builds and tests new code before merging changes into production. | Build merged changes into production. |
+| Trigger types | Triggered by a schedule or by API. | Triggered by a commit to a PR or by API. | Triggered by a merge request or by API. |
+| Destination | Builds into a production database and schema. | Builds into a staging database and ephemeral schema, lived for the lifetime of the PR. | Builds into a production database and schema. |
+| Execution mode | Runs execute sequentially, so as to not have collisions on the underlying DAG. | Runs execute in parallel to promote team velocity. | Runs execute sequentially, so as to not have collisions on the underlying DAG. |
+| Efficiency run savings | Detects over-scheduled jobs and cancels unnecessary runs to avoid queue clog. | Cancels existing runs when a newer commit is pushed to avoid redundant work. | N/A |
+| State comparison | Only sometimes needs to detect state. | Almost always needs to compare state against the production environment to build on modified code and its dependents. | Does not need to detect state. |
+| Job run duration | Limit is 24 hours. | Limit is 24 hours. | Limit is 24 hours. |

website/docs/docs/deploy/merge-jobs.md

@@ -0,0 +1,38 @@
+---
+title: "Merge jobs in dbt Cloud"
+sidebar_label: "Merge jobs"
+description: "Learn how to trigger a dbt job run when a Git pull request merges."
+---
+
+# Merge jobs in dbt Cloud <Lifecycle status="beta" />
+
+You can set up a merge job to implement a continuous development (CD) workflow in dbt Cloud. The merge job triggers a dbt job to run when someone merges Git pull requests into production. This creates a seamless development experience where changes made in code will automatically update production data. 
+
+By using CD in dbt Cloud, you can take advantage of deferral to build only the edited model and any downstream changes. With merge jobs, state will be updated almost instantly, always giving the most up-to-date state information in [dbt Explorer](/docs/collaborate/explore-projects).
+
+## Prerequisites
+- You have a dbt Cloud account. 
+- You have access to the beta release for this functionality. 
+
+## Set up job trigger on Git merge {#set-up-merge-jobs}
+
+1. On your deployment environment page, click **Create Job** > **Merge Job**. 
+1. Options in the **Job settings** section:
+    - **Job name** &mdash; Specify the name for the merge job.
+    - **Description** &mdash; Provide a descripion about the job. 
+    - **Environment** &mdash; By default, it’s set to the environment you created the job from.
+1. In the **Git trigger** section, the **Run on merge** option is enabled by default. Every time a PR merges (to the main branch) in your Git repo, this job will get triggered to run. 
+1. Options in the **Execution settings** section:
+    - **Commands** &mdash; By default, it includes the `dbt build --select state:modified+` command. This informs dbt Cloud to build only new or changed models and their downstream dependents. Importantly, state comparison can only happen when there is a deferred environment selected to compare state to. Click **Add command** to add more [commands](/docs/deploy/job-commands) that you want to be invoked when this job runs.
+    - **Compare changes against an environment (Deferral)** &mdash; By default, it's set to the environment you created the job from. This option allows dbt Cloud to check the state of the code in the PR against the code running in the deferred environment, so as to only check the modified code, instead of building the full table or the entire DAG.
+1. (optional) Options in the **Advanced settings** section: 
+    - **Environment variables** &mdash; Define [environment variables](/docs/build/environment-variables) to customize the behavior of your project when this job runs.
+    - **Target name** &mdash; Define the [target name](/docs/build/custom-target-names). Similar to **Environment Variables**, this option lets you customize the behavior of the project. 
+    - **Run timeout** &mdash; Cancel this job if the run time exceeds the timeout value.
+    - **dbt version** &mdash; By default, it’s set to inherit the [dbt version](/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior.
+    - **Threads** &mdash; By default, it’s set to 4 [threads](/docs/core/connect-data-platform/connection-profiles#understanding-threads). Increase the thread count to increase model execution concurrency.
+    - **Run source freshness** &mdash; Enable this option to invoke the `dbt source freshness` command before running this job. Refer to [Source freshness](/docs/deploy/source-freshness) for more details.
+
+## Example 
+
+<Lightbox src="/img/docs/dbt-cloud/using-dbt-cloud/example-create-merge-job.png" width="90%" title="Example of creating a merge job"/>

website/sidebars.js

@@ -418,6 +418,7 @@ const sidebarSettings = {
             "docs/deploy/jobs",
             "docs/deploy/deploy-jobs",
             "docs/deploy/ci-jobs",
+            "docs/deploy/merge-jobs",
             "docs/deploy/job-commands",
           ],
         },