diff --git a/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected.png b/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected.png new file mode 100644 index 000000000..b48956cab Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected.png differ diff --git a/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected_details.png b/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected_details.png new file mode 100644 index 000000000..45460db14 Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/fancier_workflows_fail_expected_details.png differ diff --git a/packages/dolt/content/.gitbook/assets/fancier_workflows_running.png b/packages/dolt/content/.gitbook/assets/fancier_workflows_running.png new file mode 100644 index 000000000..ab808a0e5 Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/fancier_workflows_running.png differ diff --git a/packages/dolt/content/.gitbook/assets/first_workflow_running.png b/packages/dolt/content/.gitbook/assets/first_workflow_running.png new file mode 100644 index 000000000..dabe815e5 Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/first_workflow_running.png differ diff --git a/packages/dolt/content/.gitbook/assets/first_workflow_succeeded.png b/packages/dolt/content/.gitbook/assets/first_workflow_succeeded.png new file mode 100644 index 000000000..133140cac Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/first_workflow_succeeded.png differ diff --git a/packages/dolt/content/.gitbook/assets/workflow_fail_fixed.png b/packages/dolt/content/.gitbook/assets/workflow_fail_fixed.png new file mode 100644 index 000000000..fc437392d Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/workflow_fail_fixed.png differ diff --git a/packages/dolt/content/.gitbook/assets/workflow_failed.png b/packages/dolt/content/.gitbook/assets/workflow_failed.png new file mode 100644 index 000000000..4549b2cba Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/workflow_failed.png differ diff --git a/packages/dolt/content/.gitbook/assets/workflow_failed_reason.png b/packages/dolt/content/.gitbook/assets/workflow_failed_reason.png new file mode 100644 index 000000000..728eacc76 Binary files /dev/null and b/packages/dolt/content/.gitbook/assets/workflow_failed_reason.png differ diff --git a/packages/dolt/content/SUMMARY.md b/packages/dolt/content/SUMMARY.md index d6858fd54..9e699ed52 100644 --- a/packages/dolt/content/SUMMARY.md +++ b/packages/dolt/content/SUMMARY.md @@ -147,6 +147,9 @@ - [CSV](products/dolthub/api/csv.md) - [Database](products/dolthub/api/database.md) - [Hooks](products/dolthub/api/hooks.md) + - [Continuous Integration](products/dolthub/continuous-integration/README.md) + - [Getting Started](products/dolthub/continuous-integration/getting-started.md) + - [Workflow Reference](products/dolthub/continuous-integration/reference.md) - [Transform File Uploads](products/dolthub/transform-uploads.md) - [Workspaces](products/dolthub/workspaces.md) - [DoltLab](products/doltlab/README.md) diff --git a/packages/dolt/content/products/dolthub/README.md b/packages/dolt/content/products/dolthub/README.md index 629a7cc4d..8b53fdee1 100644 --- a/packages/dolt/content/products/dolthub/README.md +++ b/packages/dolt/content/products/dolthub/README.md @@ -34,3 +34,7 @@ We added a feature to [Transform DoltHub File Uploads](./transform-uploads.md). We added the workspaces concept to DoltHub as a staging area for changes made from the web. Learn what workspaces are and how to use them most effectively. + +- [Continuous Integration](./continuous-integration/README.md) + +DoltHub and DoltLab support continuous integration (CI) testing which allow you to validate changes before you commit them on your primary branch. Learn how to configure and run CI on your DoltHub and DoltLab databases. diff --git a/packages/dolt/content/products/dolthub/continuous-integration/README.md b/packages/dolt/content/products/dolthub/continuous-integration/README.md new file mode 100644 index 000000000..f76022614 --- /dev/null +++ b/packages/dolt/content/products/dolthub/continuous-integration/README.md @@ -0,0 +1,89 @@ +# DoltHub/DoltLab Continuous Integration (CI) + +DoltHub and DoltLab support continuous integration (CI) testing which allow you to validate changes before you commit them on your primary branch. + +Continuous integration (CI) testing originated as a software development best practice where automated tests run against incoming code changes pushed by software developers who are collaborating on a code repository. + +If a developer pushes changes that fail to pass the automated tests, the proposed changes are rejected. This practice ensures that only valid, high quality changes get committed on the primary build branch, resulting in fewer bugs, and higher developer productivity. + +Dolt's revolutionary technology that marries Git and MySql now allows for CI testing on data and is supported on both DoltHub and DoltLab. In the same way the proposed code changes undergo automated tests to ensure they're valid, proposed data changes on a DoltHub or DoltLab database can also undergo automated tests to assert their validity. + +The following sections will introduce you to how CI works with Dolt, DoltHub and DoltLab and help you setup CI testing for your own databases. + +# CI starts with Dolt + +CI configuration for a DoltHub or DoltLab database is stored in the database itself. At the time of this writing, in order to add CI configuration to a DoltHub or DoltLab database, you will need to have a local Dolt client version >= [v1.45.3](https://github.com/dolthub/dolt/releases/tag/v1.45.3) and will have to clone a copy of the the database. In order to configure CI on the database, you will use Dolt's CI CLI commands. + +## Dolt CI Commands + +The primary interface for creating and editing CI configuration in a Dolt database is via the `dolt ci` CLI command. These commands aim to simplify CI configuration in Dolt, so that users do not need to manually interact with the underlying CI tables directly. + +The `dolt ci` commands as of Dolt v1.45.3 are: + +- [dolt ci init](../../../reference/cli/cli.md#dolt-ci-init). This command creates internal database tables used to store continuous integration configuration. +- [dolt ci destroy](../../../reference/cli/cli.md#dolt-ci-destroy). This command drops all database tables used to store continuous integration configuration. +- [dolt ci import](../../../reference/cli/cli.md#dolt-ci-import). This command will import a Dolt continuous integration workflow file into the database. +- [dolt ci export](../../../reference/cli/cli.md#dolt-ci-export). This command will export a Dolt continuous integration workflow by name. +- [dolt ci ls](../../../reference/cli/cli.md#dolt-ci-ls). This command lists existing Dolt continuous integration workflows by name. +- [dolt ci remove](../../../reference/cli/cli.md#dolt-ci-remove). This command removes a Dolt continuous integration workflow by name. + +The `dolt ci init` command is the starting point for adding CI to a Dolt database, since it creates the underlying tables Dolt needs to begin storing configuration. To get started adding CI to a Dolt database, follow our [getting started guide](). + +# Workflows + +Borrowing from [GitHub Actions](https://github.com/features/actions) terminology, Dolt CI configuration is also defined as _workflows_ and follows their same general syntax and definitions. Workflows are yaml files that define when CI on a database should run, and what should happen during the course of that run. Though workflows in Dolt are defined and edited as files, Dolt does not store these files directly. Instead, it parses these files and only stores the relevant content of each file in its internal CI tables. These tables are then read by DoltHub and DoltLab to enact the defined CI runs. + +More specifically, a workflow file specifies _when_ it should run, by the Events defined in it, and _what_ should happen during the run by the Jobs defined in it. + +# Events + +Events are specific activities that occur in a DoltHub or DoltLab database that trigger a workflow to run. One such event might be the pushing of a branch to the database, known as a `push` event, or the opening of a pull request on a database, a `pull_request` event. When these events occur on a database that contains a workflow that specifies it should run on these events, DoltHub and DoltLab run them. + +For a complete list of events that trigger workflows, please see the [workflow reference](./reference.md). + +# Jobs + +In addition to Events, A workflow file also contains Jobs. In the context of a workflow, Jobs define what should happen when a workflow runs. This definition consists of a series of programmatic Steps that DoltHub or DoltLab will execute during the course of a workflow run. These workflow Jobs are somewhat related to DoltHub and DoltLab _Jobs_, although at this time their relationship has no direct impact on the end-user. + +These DoltHub/DoltLab Jobs, are the automated asynchronous machinery that allow DoltHub and DoltLab to run long running processes to do programmatic work outside of its main API. These come in different types and depending on their type, do things like merge pull requests, or import a file uploaded by a user into a database. With the addition of CI on DoltHub and DoltLab, a new type of Job was added, a Dolt CI Job. This is the type of DoltHub/DoltLab Job executes a workflow Job as it is defined in the workflow file. + +# Steps + +A workflow Job is made up of a series of Steps. A step, in its current form, is a single Saved Query that will run against the database as the "check", or test, that asserts the database branch's validity. Steps run in the order they're defined and will "pass", or succeed, if the Saved Query they execute completes without error and if the defined expected SQL results match the actual SQL results returned from the Saved Query. + +For more information on Steps, please see the [workflow reference](./reference.md). + +## Saved Query + +A [Saved Query](../../../reference/sql/version-control/saved-queries.md) is a SQL query that is stored and versioned in a Dolt database. For the purpose of DoltHub and DoltLab CI, this allows users to write a SQL query that will be executed on command at a later time, during a CI run. + +For example, take the simple SQL query "show tables;". This can be added to a Dolt database as a saved query using the [dolt sql command](../../../reference/cli/cli.md#dolt-sql) with the `--save` flag. + +```bash +$ dolt sql --save "Show tables query" -q "show tables;" +``` + +The query is saved under the name "Show tables query", and can be executed at anytime with the `-x` flag. + +```bash +$ dolt sql -x "Show tables query" +``` + +In a Dolt CI workflow file, this saved query can be reference by name as a Step during the execution of a workflow Job. + +```yaml +name: example workflow +on: push + branches: [main] +jobs: + - name: example job + steps: + - name: step 1 + saved_query_name: "Show tables query" +``` + +During the execution of the example workflow defined above, the "Show tables query" will be executed whenever the "example job" runs. This will result in the SQL query "show tables;" running against the database. + +Saved queries are currently the primary method for defining tests or checks on a Dolt database. + +For more information on Saved Query Steps, please see the [workflow reference](./reference.md). \ No newline at end of file diff --git a/packages/dolt/content/products/dolthub/continuous-integration/getting-started.md b/packages/dolt/content/products/dolthub/continuous-integration/getting-started.md new file mode 100644 index 000000000..d87df1ba2 --- /dev/null +++ b/packages/dolt/content/products/dolthub/continuous-integration/getting-started.md @@ -0,0 +1,416 @@ +--- +title: Getting Started with DoltHub/DoltLab CI +--- + +CI for DoltHub and DoltLab requires [Dolt v1.45.3](https://github.com/dolthub/dolt/releases/tag/v1.45.3). This release contains the `dolt ci` command you will use to configure CI to run. + +To start, let's ensure we have the correct Dolt version installed locally. + +```bash +% dolt version +dolt version 1.45.3 +``` + +Now, let's clone a database that's hosted on DoltHub that we want to run CI tests on. + +I've created the [fork](https://docs.dolthub.com/concepts/dolthub/forks), [dolthub/options](https://www.dolthub.com/repositories/dolthub/options), of the popular DoltHub database[post-no-preference/options](https://www.dolthub.com/repositories/post-no-preference/options), and cloned a copy of my fork locally. + +```bash +% dolt clone dolthub/options +cloning https://doltremoteapi.dolthub.com/dolthub/options +% cd options +% dolt status +On branch master +Your branch is up to date with 'origin/master'. +nothing to commit, working tree clean +``` + +The first step required to enable a Dolt database to run CI is to run the [dolt ci init](../../../reference/cli/cli.md#dolt-ci-init) command. This command will create Dolt's internal CI tables and also writes a new commit to the branch. + +```bash +% dolt ci init +% dolt log -n 1 +commit mptat9ijrblrb2q4j2digq9miav3vfv0 (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 15:36:27 -0800 2024 + + Successfully initialized Dolt CI + +% +``` + +After CI initialization, we need to create the workflow file that will define our CI tests. + +# Defining a Workflow + +Modeled after GitHub Action's [Workflows](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions), Dolt CI is configured with a yaml file that gets imported into the database. + +Let's create an example `workflow.yaml` file now. + +```yaml +# workflow.yaml +name: my first DoltHub workflow +on: + push: + branches: + - master +jobs: + - name: validate tables + steps: + - name: assert expected tables exist + saved_query_name: show tables + expected_rows: "== 2" +``` + +The above `workflow.yaml` definition should look pretty familiar to GitHub Action's users. + +It defines a new Dolt workflow named "my first DoltHub workflow" in the top-level `name` field, specifies when this workflow should run in the `on` field, and what should happen when the workflow runs, defined in the `jobs` field. Each of these top-level fields is required. + +A Workflow's `name` must be unique and is case-insensitive. + +The `on` field defines when the workflow should run, or rather, what [Events]() should trigger the workflow to run. The above workflow is configured to run whenever a `push` to this database's `master` branch occurs. + +`jobs` defines the work to be performed when the workflow is run. Each workflow Job must have a unique `name` and at least one step defined in the `steps` field. Currently, these [Steps]() are where Dolt CI differs the most from GitHub Actions. + +In GitHub Actions, a workflow step, or action step, can be the running of an arbitrary binary or snippet of code that is executed as part of a Job. For Dolt CI though, at least in its current form, a job step can _only_ execute a Saved Query, which must be identified by name in the `saved_query_name` field. + +A [Saved Query](https://docs.dolthub.com/sql-reference/version-control/saved-queries) in Dolt, is an arbitrary SQL query stored in the database for execution at a later time. By specifying the name of the saved query in the `workflow.yaml` file, we are configuring CI to execute the "show tables" saved query against the `master` branch, whenever a push to `master` occurs. + +Additionally, each "step" optionally allows an `expected_rows` or `expected_columns` field to be defined, which can be used to assert the number of rows or columns in the resulting output of the saved query. + +For this simple example, we will assert that the number of rows returned from our "show tables" saved query will be equal to (`==`), 2. + +Let's save this file, and store our new workflow in the database. + +To do this, we simply use the `dolt ci import ` command. + +```bash +% dolt ci import workflow.yaml +% dolt log -n 1 +commit 0r25jqhrh26p0s9g7s8pes6qdrmq7bf0 (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 15:37:01 -0800 2024 + + Successfully stored workflow: my first DoltHub workflow + +% +``` + +Like the `dolt ci init` command earlier, this command also automatically creates a new commit. At this point the file we created `workflow.yaml` is no longer needed, as the configuration has been persisted in the Dolt database. + +If we ever need this file again, we can simply list the defined workflows in the database with the `dolt ci ls` command, then export the workflow back to yaml with the `dolt ci export ` command. + +```bash +% dolt ci ls +my first DoltHub workflow +% dolt ci export "my first dolthub workflow" +Dolt CI Workflow 'my first DoltHub workflow' exported to /Users/dustin/doltdbs/options/my_first_DoltHub_workflow.yaml. +% ls +my_first_DoltHub_workflow.yaml +% +``` + +The final step we need to perform on our local database is to define the saved query named "show tables". + +# Defining a saved query + +A saved query can be added by using the [dolt sql command](../../../reference/cli/cli.md#dolt-sql) with the `--save` option. And, as the name of our saved query suggests, we'll save the query "SHOW TABLES;". + +```bash +% dolt sql --save "show tables" -q "SHOW TABLES;" ++--------------------+ +| Tables_in_options | ++--------------------+ +| option_chain | +| volatility_history | ++--------------------+ + +% dolt status +On branch master +Your branch is ahead of 'origin/master' by 1 commit. + (use "dolt push" to publish your local commits) + +Untracked tables: + (use "dolt add " to include in what will be committed) + new table: dolt_query_catalog +``` + +Above we can see the expected output of the "show tables" saved query. The results have two rows, one row for each table in the database. + +After creating the saved query, we can see the creation of the internal `dolt_query_catalog` table which stores saved queries. We now need to add and commit this new table to our database. + +```bash +% dolt add . +% dolt commit -m 'add show tables saved query' +commit jn5n8pqc43hqs59hgolinf2mrhhkncm7 (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 15:38:35 -0800 2024 + + add show tables saved query + +% +``` + +With the workflow and saved query defined on the database, we can push our updates to DoltHub. + +```bash +% dolt push origin master +/ Uploading... +To https://doltremoteapi.dolthub.com/dolthub/options + * [new branch] master -> master +% +``` + +# Workflow Jobs on DoltHub + +Once we push the `master` branch, DoltHub will run our workflow for the first time. It does this by creating a new Dolt CI Job, in the same way it creates Jobs for pull request merges. + +Dolt CI Jobs are visible on from the "Jobs" tab. + +![Running Workflow Job](../../../.gitbook/assets/first_workflow_running.png) + +Here you can see the workflow job we defined in our yaml file "validate tables" is now running. Notice that for the time being, all Dolt CI Jobs will say they were created by the database owner, regardless of the person responsible for the `push` event. This will be fixed at a later date. + +![Succeeded Workflow Job](../../../.gitbook/assets/first_workflow_succeeded.png) + +If the Dolt CI Job is successful, meaning the saved query succeeded and the expected number of rows were found, the Job will have status "Succeeded". If the Job failed, the status would be "Failed" and we would see a relevant failure message on the Job's detail page. + +To demonstrate what this looks like, let's update our `workflow.yaml` file to include another `step`. This time, let's add a step for a saved query that does not exist in the database. + +```yaml +# workflow.yaml +name: my first DoltHub workflow +on: + push: + branches: + - master +jobs: + - name: validate tables + steps: + - name: assert expected tables exist + saved_query_name: show tables + expected_rows: "== 2" + - name: assert table option_chain exists + saved_query_name: option_chain exists +``` + +You can see that we've now added a step called "assert table option_chain exists" to our workflow, which uses a saved query "option_chain exists". Let's import these new changes into our local database, but skip saving the saved query "option_chain exists". + +```bash +% dolt ci import workflow.yaml +% dolt log -n 1 +commit gngghlouuq6g4k8fs8qpldvr0scfcjvr (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 15:56:00 -0800 2024 + + Successfully stored workflow: my first DoltHub workflow + +% dolt push origin master +- Uploading... +To https://doltremoteapi.dolthub.com/dolthub/options + * [new branch] master -> master +% +``` + +Now with our workflow configuration updated and pushed to DoltHub, we can go check the status of our new Workflow Job. + +![Failed Workflow Job](../../../.gitbook/assets/workflow_failed.png) + +As expected, the Workflow Job that ran on `push` now failed. And if we click "View details" we can see that it's because we did not add the saved query to the database. + +![Failed Workflow Job Reason](../../../.gitbook/assets/workflow_failed_reason.png) + +Ok, so let's fix the step we just added by adding the saved query "option_chain exists" to the database and pushing the changes. + +```bash +% dolt sql --save "option_chain exists" -q "select * from option_chain limit 1;" ++------------+------------+------------+--------+----------+-------+-------+--------+--------+--------+---------+--------+--------+ +| date | act_symbol | expiration | strike | call_put | bid | ask | vol | delta | gamma | theta | vega | rho | ++------------+------------+------------+--------+----------+-------+-------+--------+--------+--------+---------+--------+--------+ +| 2019-02-09 | A | 2019-02-15 | 65.00 | Call | 10.50 | 11.25 | 0.2705 | 1.0000 | 0.0000 | -0.0046 | 0.0000 | 0.0124 | ++------------+------------+------------+--------+----------+-------+-------+--------+--------+--------+---------+--------+--------+ + +% dolt status +On branch master +Your branch is up to date with 'origin/master'. + +Changes not staged for commit: + (use "dolt add
" to update what will be committed) + (use "dolt checkout
" to discard changes in working directory) + modified: dolt_query_catalog +% dolt add . +% dolt commit -m 'add option_chain exists saved query' +commit g8hm71ar28djfv1q08uvphn44njuecb7 (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 16:04:15 -0800 2024 + + add option_chain exists saved query +% dolt push origin master +\ Uploading... +To https://doltremoteapi.dolthub.com/dolthub/options + * [new branch] master -> master +``` + +And after that latest Workflow Job completes, we can see that our "validate tables" Job is passing again! + +![Failed Workflow Fixed](../../../.gitbook/assets/workflow_fail_fixed.png) + +# Getting fancier + +Let's update our `workflow.yaml` once more, but get a little fancier with it. + +```yaml +# workflow.yaml +name: my first DoltHub workflow +on: + push: + branches: + - master +jobs: + - name: validate tables + steps: + - name: assert expected tables exist + saved_query_name: show tables + expected_rows: "== 2" + - name: assert table option_chain exists + saved_query_name: option_chain exists + - name: assert table volatility_history + saved_query_name: volatility_history exists + - name: validate schema + steps: + - name: assert 13 option_chain columns exist + saved_query_name: check option_chain column length + expected_columns: "<= 13" + - name: assert call_put column exist + saved_query_name: check option_chain.call_put exists + expected_columns: "== 1" + - name: assert 16 volatility_history columns exist + saved_query_name: check volatility_history column length + expected_columns: ">= 16" + - name: assert act_symbol column exist + saved_query_name: check volatility_history.act_symbol exists + expected_columns: "== 1" + - name: check data + steps: + - name: assert option_chain table has data + saved_query_name: check option_chain data + expected_rows: "> 0" + - name: assert volatility_history table has data + saved_query_name: check volatility_history data + expected_rows: "> 0" +``` + +Above, we've done quite a bit more than before. With this updated workflow we now have added additional `job` definitions that will check each tables' schema, and ensure each table has data. + +After importing this new `workflow.yaml` into our local database, we create all of the saved queries we've referenced above in the file. The queries for each are shown in the `dolt_query_catalog` table below. + +```bash +% dolt sql -r vertical -q "select * from dolt_query_catalog;" +*************************** 1. row *************************** + id: check option_chain column length +display_order: 4 + name: check option_chain column length + query: select * from option_chain limit 1; + description: + +*************************** 2. row *************************** + id: check option_chain data +display_order: 8 + name: check option_chain data + query: select * from option_chain limit 1; + description: + +*************************** 3. row *************************** + id: check option_chain.call_put exists +display_order: 5 + name: check option_chain.call_put exists + query: select call_put from option_chain limit 1; + description: + +*************************** 4. row *************************** + id: check volatility_history column length +display_order: 6 + name: check volatility_history column length + query: select * from volatility_history limit 1; + description: + +*************************** 5. row *************************** + id: check volatility_history data +display_order: 9 + name: check volatility_history data + query: select * from volatility_history limit 1; + description: + +*************************** 6. row *************************** + id: check volatility_history.act_symbol exists +display_order: 7 + name: check volatility_history.act_symbol exists + query: select act_symbol from volatility_history limit 1; + description: + +*************************** 7. row *************************** + id: option_chain exists +display_order: 2 + name: option_chain exists + query: select * from option_chain limit 1; + description: + +*************************** 8. row *************************** + id: show tables +display_order: 1 + name: show tables + query: SHOW TABLES; + description: + +*************************** 9. row *************************** + id: volatility_history exists +display_order: 3 + name: volatility_history exists + query: select * from volatility_history limit 1; + description: + +% +``` + +After we push these new changes to DoltHub, they'll be live. + +Now, let's say that hypothetically, a new committer, unaware of the updated workflow we've defined, comes along and decides to delete all data from the `option_chain` table and pushes this change to `master`. + +```bash +% dolt sql -q "delete from option_chain;" +Query OK, 71203454 rows affected (0.00 sec) +% dolt status +On branch master +Your branch is up to date with 'origin/master'. + +Changes not staged for commit: + (use "dolt add
" to update what will be committed) + (use "dolt checkout
" to discard changes in working directory) + modified: option_chain +% dolt add . +% dolt commit -m 'remove option_chain data' +commit gjo41are9nbo4ocq9faapickmqtum26q (HEAD -> master) +Author: 😺😺😺😺 +Date: Wed Nov 13 19:00:31 -0800 2024 + + remove option_chain data + +% dolt push origin master +- Uploading... +To https://doltremoteapi.dolthub.com/dolthub/options + * [new branch] master -> master +``` + +Our updated workflow defined for this database will kick-off each of the Workflow Jobs, as seen in the image below. + +![Fancier Workflows Running](../../../.gitbook/assets/fancier_workflows_running.png) + +But, we'd expect the "check data" Workflow Job to fail. And, it does. + +![Fancier Workflows Failed](../../../.gitbook/assets/fancier_workflows_fail_expected.png) + +If we click "View details", we can see the failure resulted from expecting > 0 rows, but got 0. + +![Fancier Workflows Failed Details](../../../.gitbook/assets/fancier_workflows_fail_expected_details.png) + + diff --git a/packages/dolt/content/products/dolthub/continuous-integration/reference.md b/packages/dolt/content/products/dolthub/continuous-integration/reference.md new file mode 100644 index 000000000..84ced7eb5 --- /dev/null +++ b/packages/dolt/content/products/dolthub/continuous-integration/reference.md @@ -0,0 +1,109 @@ +--- +title: Workflow Reference +--- + +Workflows are yaml files stored in a Dolt database that specify one or more CI Jobs and identify when those Job(s) should run. + +```yaml +name: "workflow name" +on: + push: + branches: + - main + pull_request: + branches: + - main +jobs: + - name: "job name" + steps: + - name: "step name" + saved_query_name: "saved query name" + expected_rows: "== 2" + expected_columns: "== 1" +``` + +# name + +_String_. The case-insensitive name of the workflow, must be unique. Required. + +# on + +`on` identifies the events that should trigger the workflow to run. Required. + +# on.push + +Runs workflow whenever a `push` event occurs. Optional. + +A `push` event refers to a branch head update on the remote database, usually following the [dolt push](../../../reference/cli/cli.md#dolt-push) command. + +# on.pull_request + +Runs workflow whenever a `pull_request` event occurs. Optional. + +A `pull_request` event refers to any "activity" or action involving a pull request on the remote database. Activities on pull request might include, but are not limited to, opening a pull request, closing a pull request, or synchronizing a pull request. + +# on..branches + +_List_ _of_ _Strings_. The `branches` filter indicates which branch(es) should cause the workflow to run. Required. + +For example, if the `main` branch is listed under `on.push.branches`, then only a push to `main` will trigger the workflow to run. + +In the case of `on.pull_request.branches`, branches listed refer to the base branch of the pull request. If `main` is specified as a branch in this case, a pull request opened with `main` as its base branch will trigger the workflow. + +# on.pull_request.activities + +_List_ _of_ _Strings_. The `activities` filter indicates which pull request activity types should trigger a workflow. Optional. + +Supported types as of Dolt v1.45.3 are: + +- opened +- closed +- reopened + +# jobs + +`jobs` specifies one or more Jobs a workflow should run when it is triggered. Required. + +# jobs.name + +_String_. The case-insensitive name of a job, must be unique. Required. + +# jobs.steps + +`steps` are a sequence of checks or tests to execute against the database during a workflow run. Required. + +Steps run in the order they are defined. + +# jobs.steps.name + +_String_. The case-insensitive name of a step, must be unique. Required. + +# jobs.steps.saved_query_name + +_String_. The name of the [saved query](../../../reference/sql/version-control/saved-queries.md) that should be executed during the workflow run. Required. + +# jobs.steps.expected_rows + +_String_. The number of expected rows resulting from the execution of the named saved query. Optional. + +This should be in the format: ` `, for example, `!= 15`. Valid comparators are: + +- == for equals +- \!= for not equals +- > for greater than +- >= for greater than or equal to +- < for less than +- <= for less than or equal to + +# jobs.steps.expected_columns + +_String_. The number of expected columns resulting from the execution of the named saved query. Optional. + +This should be in the format: ` `, for example, `!= 15`. Valid comparators are: + +- == for equals +- \!= for not equals +- > for greater than +- >= for greater than or equal to +- < for less than +- <= for less than or equal to