This is an automated email from the ASF dual-hosted git repository. lynwee pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 9444bb0eb50eef159991a402d5f6c63e3e1b4c69 Author: Startrekzky <[email protected]> AuthorDate: Thu Dec 28 22:57:49 2023 +0800 docs: update DORA manuals in v0.20 --- .../images/dora-github-connection-1.png | Bin 0 -> 58828 bytes .../images/dora-jira-connection-1.png | Bin 0 -> 41277 bytes .../images/dora-jira-connection-2.png | Bin 0 -> 43424 bytes .../Configuration/images/dora-project-1.png | Bin 0 -> 31857 bytes .../Configuration/images/dora-project-2.png | Bin 0 -> 13586 bytes .../Configuration/images/dora-project-3.png | Bin 0 -> 46271 bytes .../Configuration/images/dora-webhook-1.png | Bin 0 -> 99061 bytes .../Configuration/images/dora-webhook-2.png | Bin 0 -> 53290 bytes .../Configuration/images/dora-webhook-3.png | Bin 0 -> 20692 bytes versioned_docs/version-v0.20/DORA.md | 147 +++++++++++---------- 10 files changed, 74 insertions(+), 73 deletions(-) diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-github-connection-1.png b/versioned_docs/version-v0.20/Configuration/images/dora-github-connection-1.png new file mode 100644 index 0000000000..f9986f1e6a Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-github-connection-1.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-1.png b/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-1.png new file mode 100644 index 0000000000..113a9fcfcc Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-1.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-2.png b/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-2.png new file mode 100644 index 0000000000..f3619ce7be Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-jira-connection-2.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-project-1.png b/versioned_docs/version-v0.20/Configuration/images/dora-project-1.png new file mode 100644 index 0000000000..94e1380723 Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-project-1.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-project-2.png b/versioned_docs/version-v0.20/Configuration/images/dora-project-2.png new file mode 100644 index 0000000000..249b0ab00c Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-project-2.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-project-3.png b/versioned_docs/version-v0.20/Configuration/images/dora-project-3.png new file mode 100644 index 0000000000..dd08396cff Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-project-3.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-webhook-1.png b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-1.png new file mode 100644 index 0000000000..679a420a93 Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-1.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-webhook-2.png b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-2.png new file mode 100644 index 0000000000..863d0a9a46 Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-2.png differ diff --git a/versioned_docs/version-v0.20/Configuration/images/dora-webhook-3.png b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-3.png new file mode 100644 index 0000000000..23e351785f Binary files /dev/null and b/versioned_docs/version-v0.20/Configuration/images/dora-webhook-3.png differ diff --git a/versioned_docs/version-v0.20/DORA.md b/versioned_docs/version-v0.20/DORA.md index 9c5fb8c8a1..8161eca48a 100644 --- a/versioned_docs/version-v0.20/DORA.md +++ b/versioned_docs/version-v0.20/DORA.md @@ -35,91 +35,77 @@ DORA metrics help teams and projects measure and improve software development pr ## How to implement DORA metrics with Apache DevLake? -You can set up DORA metrics in DevLake in a few steps: - -- **Install**: [Getting Started](./GettingStarted) -- **Collect**: Collect data via blueprint - - In the blueprint, select the data you wish to collect, and make sure you have selected the data required for DORA metrics - - Configure DORA-related transformation rules to define `deployments` and `incidents` - - Select a sync frequency for your data, save and run the blueprint. -- **Report**: DevLake provides a built-in DORA dashboard. See an example screenshot below or check out our [live demo](https://grafana-lake.demo.devlake.io/grafana/d/qNo8_0M4z/dora?orgId=1). +DevLake measures DORA metrics at the [project level](GettingStarted/HowToOrganizeDevlakeProjects.md#2-why-is-it-important-to-organize-projects). You can set up DORA metrics in a few steps: + +- **Install**: via [Docker Compose](GettingStarted/DockerComposeSetup.md) or [Helm](GettingStarted/HelmSetup.md). +- **Configure and collect data**: + - Create [data connections](Overview/KeyConcepts.md#data-connection) to retrieve the data from various tools such as Jira, GitHub, Jenkins, etc. + - Configure the DORA-related [scope config](Overview/KeyConcepts.md#scope-config) to define `deployments` and `incidents`. + - Create a DevLake project, and associate the data connections with the project. Collect data to see DORA metrics +- **Report**: DevLake provides a built-in DORA dashboard and another dashboard to help you debug DORA. See an example screenshot below or check out our [live demo](https://grafana-lake.demo.devlake.io/grafana/d/qNo8_0M4z/dora?orgId=1). +  -DevLake now supports Jenkins, GitHub Action and GitLabCI as data sources for `deployments` data; Jira, GitHub issues, and TAPD as the sources for `incidents` data; Github PRs, GitLab MRs as the sources for `changes` data. +DevLake now supports Jenkins, GitHub Action, GitLab CI, BitBucket and Azure Pipelines as the data sources for `deployments`; Jira boards, GitHub issues, TAPD workspaces and Zentao issues as the sources for `incidents` data; Github/BitBucket/Azure/GitLab repos as the sources for `Pull Requests` and `Commits`. -If your CI/CD tools are not listed on the [Supported Data Sources](./Overview/SupportedDataSources) page, have no fear! DevLake provides incoming webhooks to push your `deployments` data to DevLake. The webhook configuration doc can be found [here](./Configuration/webhook/). +If your CI/CD or incident management tools are not listed on the [Supported Data Sources](./Overview/SupportedDataSources.md) page, have no fear! DevLake provides incoming webhooks to push your `deployments` or `incidents` to DevLake. The webhook configuration doc can be found [here](./Configuration/webhook.md). ## A real-world example -Let's walk through the DORA implementation process for a team with the following toolchain +Let us walk through the DORA implementation process for a [project team](GettingStarted/HowToOrganizeDevlakeProjects.md#43-measuring-dora-at-the-team-level) with the following toolchain - Source Code Management and Code Review: GitHub -- CI/CD: GitHub Actions + CircleCI -- Issue Tracking: Jira +- Continous Deployments: GitHub Actions & CircleCI +- Incident management: Jira -Calculating DORA metrics requires three key entities: **Code changes**, **deployments**, and **incidents**. Their exact definitions of course depend on a team's DevOps practice and varies team by team. For the team in this example, let's assume the following definition: +Calculating DORA metrics requires three key entities: **Pull requests**, **deployments**, and **incidents**. Their exact definitions of course depend on a project's DevOps practice and vary project by project. For the project in this example, let us assume the following definition: - Code Changes: All commits and pull requests in GitHub. -- Deployments: GitHub workflow run whose jobs contain "deploy" in their names and all CircleCI deployments. +- Deployments: GitHub workflow run whose jobs contain "deploy" and "push-image" in their names and CircleCI deployments. - Incidents: Jira issues whose type is "DORA Incident" -In the next section, we'll demonstrate how to configure DevLake to implement DORA metrics for the aforementioned example team. +In the next section, we will demonstrate how to configure DevLake to implement DORA metrics for the aforementioned example project team. -### Collect GitHub & Jira data via `Project` +### Step 1 - Configure GitHub & Jira connections -1. Visit the config-ui at `http://localhost:4000` -2. Create a project: 'project1'. Go to 'project1' and create a blueprint. +1.1 Visit the config-ui at `http://localhost:4000`. -  +1.2 Go to the __Connections__ page. Create a Jira connection. -  +1.3 Add your project's Jira boards. Click the `Associate Scope Config` icon to configure for DORA metrics. -3. Add a Jira and a GitHub connection. Click `Next Step` +  -  + To make it simple, fields with the  label are DORA-related configurations for every data source. Via these fields, you can define what "incidents" and "deployments" are for each data source. -4. Select Jira boards and GitHub repos to collect, click `Next Step` + This project uses Jira issue type `DORA Incident` as "incident". Please select the `DORA Incident` for the `Incident` field. Jira issues belonging to this type will be converted to 'INCIDENT' in DevLake. + +  -  -5. Click the `Associate Transformation` icon to configure the transformation rules to measure DORA metrics +1.4 Create a GitHub connection. Add the GitHub repositories. Once added, associate the scope configuration with the repositories. + + In this project, the GitHub CI jobs 'deploy' and 'push-image' are recognized as deployments. To identify these deployments, please use the pattern '(?i)(deploy|push-image)'. GitHub Workflow runs that match this pattern will be transformed into 'deployments' and recorded in the table 'cicd_deployments' in DevLake. + +  + + Please note that starting from v0.20, DevLake automatically collects GitHub deployments and converts them into DevLake deployments by default. -  +### Step 2 - Collect CircleCI deployments via webhook - To make it simple, fields with a  label are DORA-related configurations for every data source. Via these fields, you can define what "incidents" and "deployments" are for each data source. +Using CircleCI as an example, we demonstrate how to actively push data to DevLake using the Webhook approach, in cases where DevLake does not have a plugin specific to that tool to pull data from your data source. Please note that CircleCI will be supported from v0.21. - - This team uses Jira issue types `DORA Incident` as "incident", so choose the field `DORA Incident`. Jira issues in this type will be transformed to "incidents" in DevLake. -  - - This team uses the GitHub action jobs named `deploy` and `build-and-push-image` to deploy, so type in `(?i)(deploy|push-image)` to match these jobs. The workflow runs that these jobs belong to will be transformed to "deployments" in DevLake. -  +2.1 Go to the __Connections__ page. Add a webhook called 'CircleCI'. - Note: DevLake converts GitHub workflow runs as DevLake deployments in v0.17 and later versions. A workflow run is a DevLake deployment if the name of a workflow run or one of its jobs that match the regex. +2.2 Copy the curl command to register deployments to Devlake. This curl command includes a non-expired [API key](Configuration/APIKeys.md) generated automatically. -6. Configure the sync policy and click 'Save and Run Now' to start data collection. The time to completion varies by the API rate limits of different data sources and the volume of data. +  -  +2.3 Head to your CircleCI's pipelines page in a new tab. Find your deployment pipeline and click `Configuration File`. + +  -For more details, please refer to our [blueprint manuals](Configuration/Tutorial.md). - -### Collect CircleCI data via `webhook` - -Using CircleCI as an example, we demonstrate how to actively push data to DevLake using the Webhook approach, in cases where DevLake doesn't have a plugin specific to that tool to pull data from your data source. - -7. In Project1's detailed page, switch to tab 'Incoming Webhooks'. Add a webhook called 'CircleCI' - -  - -  - - -8. Click "Generate POST URL". DevLake will generate URLs that you can send JSON payloads to push `deployments` and `incidents` to Devlake. Copy the `Deployment` curl command. - -  - -9. Now head to your CircleCI's pipelines page in a new tab. Find your deployment pipeline and click `Configuration File` -  - -10. Paste the curl command copied in step 8 to the `config.yml`, change the key-values in the payload. See full payload schema [here](./Plugins/webhook/##register-a-deployment). +2.4 Paste the curl command to the `config.yml`. Change the key-values in the payload. See the full payload schema [here](./Plugins/webhook.md/#deployment). ``` version: 2.1 @@ -164,27 +150,42 @@ workflows: - deploy ``` -If you have set a [username/password](GettingStarted/Authentication.md) for Config UI, you need to add them to the curl to register a deployment: -``` -curl https://sample-url.com/api/plugins/webhook/2/deployments -X 'POST' -u 'username:password' -d '{ - \"commit_sha\":\"$CIRCLE_SHA1\", - \"repo_url\":\"$CIRCLE_REPOSITORY_URL\", - \"start_time\":\"$start_time\" - }' -``` +2.5 Run the CircleCI pipeline. Visit DevLake's DB to check if the deployments have been successfully pushed to DevLake. The deployments will appear in table [cicd_deployments](DataModels/DevLakeDomainLayerSchema.md#cicd_deployments) and [cicd_deployment_commits](DataModels/DevLakeDomainLayerSchema.md#cicd_deployment_commits) in DevLake's database. + +  + +  + + +### Step 3 - Create a project and collect data +Once all the data connections and webhooks have been configured, it is essential to associate them with a DevLake project. This association is necessary to accurately measure DORA metrics. + +3.1 Go to the __Projects__ page. Create 'project1' and enable DORA metrics. + +  + +3.2 Add Jira and a GitHub connections to this project. + +  + + Choose the Jira boards and GitHub repos that belong to 'project1'. + +  + +3.3 Go to the __webhooks__ tab. Add the existing webhook 'CircleCI' to this project. -11. Run the modified CircleCI pipeline. Check that the request has been successfully sent. +  -  +  -12. You will find the `deployments` pushed from CircleCI in table [cicd_deployment_commits](DataModels/DevLakeDomainLayerSchema.md#domain-4---cicd) in DevLake's database. +3.4 Go to the __blueprint status__ tab, click `Collect All` to start data collection. -  +### Step 4 - View and customize DevLake's DORA dashboard -### View and customize DevLake's DORA dashboard +With all the data collected, DevLake's DORA dashboard is ready to deliver your DORA metrics and benchmarks. -With all the data collected, DevLake's DORA dashboard is ready to deliver your DORA metrics and benchmarks. You can find the DORA dashboard within the Grafana instance shipped with DevLake, ready for you to put into action. +Click the `Dashboards` on the top right corner. You can find the DORA dashboard within the Grafana instance shipped with DevLake, ready for you to put into action. You can customize the DORA dashboard by editing the underlying SQL query of each panel. @@ -195,7 +196,7 @@ For a breakdown of each metric's SQL query, please refer to the corresponding me - [Median Time to Restore Service](./Metrics/MTTR.md) - [Change Failure Rate](./Metrics/CFR.md) -If you aren't familiar with Grafana, please refer to our [Grafana doc](Configuration/Dashboards/GrafanaUserGuide.md), or jump into Slack for help. +If you are not familiar with Grafana, please refer to our [Grafana doc](Configuration/Dashboards/GrafanaUserGuide.md), or jump into Slack for help. <br/> @@ -205,10 +206,10 @@ If you aren't familiar with Grafana, please refer to our [Grafana doc](Configura ## Try it Out -To create the DORA dashboard with your own toolchain, please look at the [configuration tutorial](Configuration/Tutorial.md) for more details. +To create the DORA dashboard with your own toolchain, please look at the [configuration tutorial](Configuration/Tutorial.md) and [project organization documentation](GettingStarted/HowToOrganizeDevlakeProjects.md) for more details. <br/> ## Troubleshooting -If you run into any problem, please check the [Troubleshooting](/Troubleshooting/Configuration.md) or [create an issue](https://github.com/apache/incubator-devlake/issues) +If you run into any problem, please check the DORA debug dashboard, [DORA troubleshooting documentation](/Troubleshooting/Dashboard.md#debugging-dora-issue-metrics) or [create an issue](https://github.com/apache/incubator-devlake/issues) on GitHub.
