# GitHub

With Paradime Turbo CI, you can run and test code changes to your dbt™ project prior to merge them in your main branch, by configuring a Bolt schedule to run when a new pull request is opened against your dbt™ repository.

Paradime will build the models affected by your changed into a temporary schema, and will run tests that you have written against the changes models to validate your test are still passing. When opening a pull request, Paradime Turbo CI run status will be showing in the pull request.

{% hint style="warning" %}

## Prerequisites <a href="#pre-requisites" id="pre-requisites"></a>

1. [Install the Paradime Github app](https://docs.paradime.io/app-help/documentation/integrations/ci-cd/github) and authorize access to the dbt™ repository used in Paradime.
2. **Add an additional scheduler environment configured in Paradime, where the target is set to `ci`.** [**Check our setup guide here based on your data warehouse provider**](https://docs.paradime.io/app-help/documentation/settings/connections/scheduler-environment)**.**
   {% endhint %}

***

### How Turbo CI works <a href="#how-turbo-ci-works" id="how-turbo-ci-works"></a>

When Turbo CI is configured, Paradime will listen for the pull request event from Github - Turbo CI will run on creation, reopening and when there is a new commit in a PR.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FRsalJbJejXY47D3HNlfh%2Fimage.png?alt=media&#x26;token=b02e3300-9cc1-4283-b9a5-a3c991cb96d5" alt=""><figcaption></figcaption></figure>

When Paradime receive the webhook event, Bolt will trigger a new run based on the configuration of the Turbo CI job.

When running, models will be built in a temporary schema using the prefix **`paradime_turbo_ci_pr_`** followed by the PR number (e.g **`paradime_turbo_ci_pr_123`**). This will enabled you to see the results of your changes associated with the code in your pull request in your production data warehouse

After the pull request is merged, Paradime will delete the temporary schema created as part of the turbo CI job to keep your database in order.

***

### Configure a custom schema for CI runs <a href="#configuring-bolt-turbo-ci-job" id="configuring-bolt-turbo-ci-job"></a>

Customize you dbt™ schema generation at runtime, to make sure that when a PR is opened, Paradime Turbo CI will build and test your changed dbt™ models in a temporary schema. We will want to update the dbt™  `generate_schema_name.sql` macro.

In your dbt™ project, in your *macros* folder create a macro called: `generate_schema_name.sql` and use a similar logic as below, where when a Bolt run is executed using the `ci` target the schema where your models will be built will use the **`paradime_turbo_ci_pr`** prefix.

```sql
{% macro generate_schema_name(custom_schema_name, node) -%}

    {%- set default_schema = target.schema -%}
    {%- if target.name == 'prod' -%}

        {{ custom_schema_name | trim }}

    {%- elif target.name == 'ci' -%}

        {{ default_schema }}

    {%- else -%}

        {%- if custom_schema_name is none -%}

            {{ default_schema }}

        {%- else -%}

            {{ default_schema }}_{{ custom_schema_name | trim }}

        {%- endif -%}

    {%- endif -%}

{%- endmacro %}
```

{% hint style="info" %}
💡 Learn more about custom schemas configurations in [dbt™ documentation](https://docs.getdbt.com/docs/build/custom-schemas#advanced-custom-schema-configuration).&#x20;
{% endhint %}

***

### Deferral and State Comparison explained <a href="#deferral-and-state-comparison-explained" id="deferral-and-state-comparison-explained"></a>

When creating the Turbo CI job in Paradime, you can set your execution settings to defer to a previous run state by adding in the `deferred_schedule_name` configuration the name of the Bolt productions schedule you want to defer to

Paradime will look at the `manifest.json` from the specified schedule's most recent successful run *(unless setting the optional parameter `successful_run_only: false`)* to determined the set of new and modified dbt™ resources. In your Turbo CI commands, you can then use the `state:modified+` argument to only run the modified resources and their downstream dependencies.

**A common example is:**

```bash
dbt build --select state:modified+ --target ci
```

This will run and test all modified models with the downstream dependencies. Useful to validate that test are still passing after making changes to upstream dbt™ models.

{% hint style="info" %}
💡 Read more about state comparison check the dbt Core™ documentation [here](https://docs.getdbt.com/reference/node-selection/state-comparison-caveats).
{% endhint %}

***

### Configuring Bolt Turbo CI job <a href="#configuring-bolt-turbo-ci-job" id="configuring-bolt-turbo-ci-job"></a>

Setting up your Turbo CI Bolt Schedule is very similar to a normal bolt schedule with the addition of a couple more configurations.

A Turbo CI job differ from a bolt schedule as it involves:

* The Bolt schedule to defer to
* The `commands` to use the `state:modified+` selector to build / tests only new dbt™ models and their downstream dependencies. State comparison can only happen when there is a deferred schedule name configured to compare state to.
* Being triggered by a pull request being opened in your Github dbt™ repository

{% hint style="info" %}
**Implement using Paradime's Bolt Template -** [**Test Code Changes on Pull Request**](https://docs.paradime.io/app-help/documentation/bolt/creating-schedules/templates/ci-cd-templates/test-code-changes-on-pull-requests)**.**&#x20;
{% endhint %}

***

### View Turbo CI run Logs <a href="#view-turbo-ci-run-logs" id="view-turbo-ci-run-logs"></a>

As per other bolt schedules, you can inspect run logs for each of the Turbo CI jobs running when a pull request is opened.

{% content-ref url="../../managing-schedules/viewing-run-log-history" %}
[viewing-run-log-history](https://docs.paradime.io/app-help/documentation/bolt/managing-schedules/viewing-run-log-history)
{% endcontent-ref %}

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FdmkUgzElbOtiO92wlYo5%2Fbolt_turbo_ci_logs.png?alt=media&#x26;token=bbf48058-69b8-4bdb-a0e2-9273cf466b2b" alt=""><figcaption></figcaption></figure>

Paradime provides a set of system environment variables that can be added to your dbt™ models to inject metadata at run time to add more information to your materialized tables in your data warehouse.

These can be used to help identify which schedules run relates to a given row of data in your tables.

***

### Filter Turbo CI runs by PR number

Filter Turbo CI runs by pull request number to view all runs associated with a specific PR. This makes it easier to track the status and history of CI runs for a particular pull request.

To filter by PR number:

1. Navigate to the [Bolt](https://docs.paradime.io/app-help/documentation/bolt) and select a Turbo CI schedule
2. From the schedule detail view, scroll to **Run History** section
3. Enter PR number in text box (ex. **PR:183**)

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FvOroLU89EwFQCrVVNurB%2Fimage.png?alt=media&#x26;token=9df83917-2bf6-4ea5-b250-657b93bb66f5" alt=""><figcaption></figcaption></figure>

Additonally, you can view the status of a PR in bolt directly by hovering over the **Pull Request** section of a turbo CI run.&#x20;

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FAJTPZk4JDV7r2fbhXtHo%2Fimage.png?alt=media&#x26;token=9f51874c-b6f5-4d11-be43-01fb9a8e2982" alt=""><figcaption></figcaption></figure>

### Environment variables

Paradime provides a set of system environment variables that can be used to build custom logic for macro or schema generation when a PR is opened.

<table><thead><tr><th width="405">Vairable name</th><th>example</th></tr></thead><tbody><tr><td><code>PARADIME_TURBO_CI_PREFIX</code></td><td>paradime_turbo_ci_pr_123</td></tr></tbody></table>