This is an automated email from the ASF dual-hosted git repository.
abeizn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 7846fbdb9e docs: add webhook usage docs in a project (#454)
7846fbdb9e is described below
commit 7846fbdb9e86b2b4f59b3327279e46be8393887d
Author: abeizn <[email protected]>
AuthorDate: Fri Mar 3 21:25:05 2023 +0800
docs: add webhook usage docs in a project (#454)
* docs: add webhook usage docs in a project
* docs: update dora webhook project use
* docs: update dora webhook project use v0.15.0
* docs: update dora webhook project use v0.15.0
* docs: update the relative URL path
* docs: update the relative URL path
* docs: fix typo in DORA.md
---------
Co-authored-by: Louis.z <[email protected]>
---
docs/Configuration/webhook.md | 12 +-
docs/DORA.md | 193 +++++++++++----------
docs/Plugins/webhook.md | 9 +-
static/img/ConfigUI/project-webhook-use.png | Bin 0 -> 26762 bytes
static/img/ConfigUI/project1.png | Bin 0 -> 28336 bytes
static/img/ConfigUI/webhook-connection.png | Bin 0 -> 78276 bytes
static/img/ConfigUI/webhook-use.png | Bin 92069 -> 0 bytes
.../version-v0.15/UserManuals/ConfigUI/webhook.md | 12 +-
versioned_docs/version-v0.15/UserManuals/DORA.md | 190 ++++++++++----------
9 files changed, 223 insertions(+), 193 deletions(-)
diff --git a/docs/Configuration/webhook.md b/docs/Configuration/webhook.md
index 16f681fdd6..7fa721067e 100644
--- a/docs/Configuration/webhook.md
+++ b/docs/Configuration/webhook.md
@@ -14,11 +14,17 @@ Go to the 'Data Connections' page. Create a webhook.
We recommend that you give your webhook connection a unique name so that you
can identify and manage where you have used it later.
-### Step 2 - Use Webhooks
+### Step 2 - Create webhooks connection
-Click on Generate POST URL, and you will find four webhook URLs. Copy the ones
that suit your usage into your CI or issue-tracking systems. You can always
come back to the webhook page to copy the URLs later on.
+Click on Generate POST URL, and you will find three webhook URLs. Copy the
ones that suit your usage into your CI or issue-tracking systems. You can
always come back to the webhook page to copy the URLs later on.
-
+
+
+### Step 3 - Use webhook in a project
+
+Create a Project first, choose Incoming Webhooks, then you can `Add a Webhook`
or `Select Existing Webhooks`.
+
+
#### Put webhook on the internet
diff --git a/docs/DORA.md b/docs/DORA.md
index 54d0c4e62d..6e5007db2d 100644
--- a/docs/DORA.md
+++ b/docs/DORA.md
@@ -5,47 +5,49 @@ description: >
DORA Metrics
---
-
This document describes everything you need to know about DORA, and
implementing this powerful and practical framework in DevLake.
## What are DORA metrics?
+
Created six years ago by a team of researchers, DORA stands for "DevOps
Research & Assessment" and is the answer to years of research, having examined
thousands of teams, seeking a reliable and actionable approach to understanding
the performance of software development teams.
DORA has since become a standardized framework focused on the stability and
velocity of development processes, one that avoids the more controversial
aspects of productivity and individual performance measures.
-There are two key clusters of data inside DORA: Velocity and Stability. The
DORA framework is focused on keeping them in context with each other, as a
whole, rather than as independent variables, making the data more challenging
to misinterpret or abuse.
+There are two key clusters of data inside DORA: Velocity and Stability. The
DORA framework is focused on keeping them in context with each other, as a
whole, rather than as independent variables, making the data more challenging
to misinterpret or abuse.
-Within velocity are two core metrics:
-- [Deployment
Frequency](https://devlake.apache.org/docs/Metrics/DeploymentFrequency): Number
of successful deployments to production, how rapidly is your team releasing to
users?
-- [Lead Time for
Changes](https://devlake.apache.org/docs/Metrics/LeadTimeForChanges): How long
does it take from commit to the code running in production? This is important,
as it reflects how quickly your team can respond to user requirements.
+Within velocity are two core metrics:
+
+- [Deployment Frequency](./Metrics/DeploymentFrequency): Number of successful
deployments to production, how rapidly is your team releasing to users?
+- [Lead Time for Changes](./Metrics/LeadTimeForChanges): How long does it take
from commit to the code running in production? This is important, as it
reflects how quickly your team can respond to user requirements.
Stability is composed of two core metrics:
-- [Median Time to Restore
Service](https://devlake.apache.org/docs/Metrics/MTTR): How long does it take
the team to properly recover from a failure once it is identified?
-- [Change Failure Rate](https://devlake.apache.org/docs/Metrics/CFR): How
often are your deployments causing a failure?
+
+- [Median Time to Restore Service](./Metrics/MTTR): How long does it take the
team to properly recover from a failure once it is identified?
+- [Change Failure Rate](./Metrics/CFR): How often are your deployments causing
a failure?
-To make DORA even more actionable, there are well-established benchmarks to
determine if you are performing at "Elite", "High", "Medium", or "Low" levels.
Inside DevLake, you will find the benchmarking table available to assess and
compare your own projects.
+To make DORA even more actionable, there are well-established benchmarks to
determine if you are performing at "Elite", "High", "Medium", or "Low" levels.
Inside DevLake, you will find the benchmarking table available to assess and
compare your own projects.
## Why is DORA important?
-DORA metrics help teams and projects measure and improve software development
practices to consistently deliver reliable products, and thus happy users!
+DORA metrics help teams and projects measure and improve software development
practices to consistently deliver reliable products, and thus happy users!
## How to implement DORA metrics with Apache DevLake?
You can set up DORA metrics in DevLake in a few steps:
-- **Install**: [Getting
Started](https://devlake.apache.org/docs/GettingStarted)
+
+- **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.
+ - 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 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.
-If your CI/CD tools are not listed on the [Supported Data
Sources](https://devlake.apache.org/docs/SupportedDataSources) page, have no
fear! DevLake provides incoming webhooks to push your `deployments` data to
DevLake. The webhook configuration doc can be found
[here](https://devlake.apache.org/docs/Configuration/webhook/).
-
+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/).
## A real-world example
@@ -64,123 +66,130 @@ Calculating DORA metrics requires three key entities:
**changes**, **deployments
In the next section, we'll demonstrate how to configure DevLake to implement
DORA metrics for the aforementioned example team.
### Collect GitHub & Jira data via `blueprint`
+
1. Visit the config-ui at `http://localhost:4000`
-2. Create a `blueprint`, let's name it "Blueprint for DORA", add a Jira and a
GitHub connection. Click `Next Step`
-
+2. Create a project: 'project1'. Go to 'project1' and create a blueprint.
Let's name it "Blueprint for DORA", add a Jira and a GitHub connection. Click
`Next Step`
+ 
+ 
3. Select Jira boards and GitHub repos to collect, click `Next Step`
-
+ 
4. Click `Add Transformation` to configure for DORA metrics
-
+ 
5. To make it simple, fields with a  label
are DORA-related configurations for every data source. Via these fields, you
can define what are "incidents" and "deployments" for each data source. After
all data connections have been configured, click `Next Step`
+
- This team uses Jira issue types `Crash` and `Incident` as "incident", so
choose the two types in field "incident". Jira issues in these two types will
be transformed to "incidents" in DevLake.
- This team uses the GitHub action jobs named `deploy` and
`build-and-deploy` to deploy, so type in `(?i)deploy` to match these jobs.
These jobs will be transformed to "deployments" in DevLake.
- 
-
+ 
+
Note: The following example shows where to find GitHub action jobs. It's
easy to mix them up with GitHub workflows.
-
6. Choose sync frequency, click 'Save and Run Now' to start data collection.
The time to completion varies by data source and depends on the volume of data.
-
+ 
-For more details, please refer to our [blueprint
manuals](https://devlake.apache.org/docs/Configuration/Tutorial).
+For more details, please refer to our [blueprint
manuals](./Configuration/Tutorial).
### 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. Visit "Data Connections" page in config-ui and select "Issue/Deployment
Incoming Webhook".
+7. Go to the 'Data Connections' page. Create a webhook.
+
-8. Click "Add Incoming Webhook", give it a name, and 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.
-
-
+We recommend that you give your webhook connection a unique name so that you
can identify and manage where you have used it later.
+
+8. Create a Project first, choose Incoming Webhooks, then you can `Add a
Webhook` or `Select Existing Webhooks`. And 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](https://devlake.apache.org/docs/Plugins/webhook/##register-a-deployment).
- ```
- version: 2.1
-
- jobs:
- build:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "build"
- command: |
- echo Hello, World!
-
- deploy:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "deploy"
- command: |
- # The time a deploy started
- start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
-
- # Some deployment tasks here ...
- echo Hello, World!
-
- # Send the request to DevLake after deploy
- # The values start with a '$CIRCLE_' are CircleCI's built-in
variables
- curl https://sample-url.com/api/plugins/webhook/1/deployments -X
'POST' -d "{
- \"commit_sha\":\"$CIRCLE_SHA1\",
- \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
- \"start_time\":\"$start_time\"
- }"
-
- workflows:
- build_and_deploy_workflow:
- jobs:
- - build
- - 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/1/deployments -X 'POST' -u
'username:password' -d '{
- \"commit_sha\":\"$CIRCLE_SHA1\",
- \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
- \"start_time\":\"$start_time\"
- }'
- ```
+ 
+
+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).
+
+```
+version: 2.1
+
+jobs:
+ build:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "build"
+ command: |
+ echo Hello, World!
+
+ deploy:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "deploy"
+ command: |
+ # The time a deploy started
+ start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
+
+ # Some deployment tasks here ...
+ echo Hello, World!
+
+ # Send the request to DevLake after deploy
+ # The values start with a '$CIRCLE_' are CircleCI's built-in
variables
+ curl http://127.0.0.1:4000/api/plugins/webhook/1/deployments -X
'POST' -d "{
+ \"commit_sha\":\"$CIRCLE_SHA1\",
+ \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
+ \"start_time\":\"$start_time\"
+ }"
+
+workflows:
+ build_and_deploy_workflow:
+ jobs:
+ - build
+ - 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/1/deployments -X 'POST' -u
'username:password' -d '{
+ \"commit_sha\":\"$CIRCLE_SHA1\",
+ \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
+ \"start_time\":\"$start_time\"
+ }'
+```
11. Run the modified CircleCI pipeline. Check to verify that the request has
been successfully sent.
-
+ 
12. You will find the corresponding `deployments` in table.cicd_tasks in
DevLake's database.
-
+ 
-### 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. 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.
For a breakdown of each metric's SQL query, please refer to the corresponding
metric docs:
- - [Deployment
Frequency](https://devlake.apache.org/docs/Metrics/DeploymentFrequency)
- - [Lead Time for
Changes](https://devlake.apache.org/docs/Metrics/LeadTimeForChanges)
- - [Median Time to Restore
Service](https://devlake.apache.org/docs/Metrics/MTTR)
- - [Change Failure Rate](https://devlake.apache.org/docs/Metrics/CFR)
+
+- [Deployment Frequency](./Metrics/DeploymentFrequency)
+- [Lead Time for Changes](./Metrics/LeadTimeForChanges)
+- [Median Time to Restore Service](./Metrics/MTTR)
+- [Change Failure Rate](./Metrics/CFR)
If you aren't familiar with Grafana, please refer to our [Grafana
doc](Configuration/Dashboards/GrafanaUserGuide.md), or jump into Slack for help.
<br/>
-:tada::tada::tada: Congratulations! You are now a DevOps Hero, with your own
DORA dashboard!
+:tada::tada::tada: Congratulations! You are now a DevOps Hero, with your own
DORA dashboard!
<br/><br/>
-
## Try it Out
To create the DORA dashboard with your own toolchain, please look at the
[configuration tutorial](Configuration/Tutorial.md) for more details.
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index 3d180f29dd..0276c627ee 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -138,7 +138,6 @@ needs to be called when an issue or incident is created.
The body should be a JS
| Keyname | Required | Notes
|
| :-----------------------: | :------: |
------------------------------------------------------------- |
-| board_key | ✔️ Yes | issue belongs to which board/project
|
| url | ✖️ No | issue's URL
|
| issue_key | ✔️ Yes | issue's key, needs to be unique in a
connection |
| title | ✔️ Yes |
|
@@ -168,22 +167,22 @@ More information about these columns at
[DomainLayerIssueTracking](https://devla
#### Register Issues - Close Issues (Optional)
-`POST
https://sample-url.com/api/plugins/webhook/1/issue/:boardKey/:issueId/close`
+`POST https://sample-url.com/api/plugins/webhook/1/issue/:issueId/close`
-needs to be called when an issue or incident is closed. Replace `:boardKey`
and `:issueId` with specific strings and keep the body empty.
+needs to be called when an issue or incident is closed. Replace `:issueId`
with specific strings and keep the body empty.
#### Register Issues - Sample API Calls
Sample CURL for Issue Creating :
```
-curl https://sample-url.com/api/plugins/webhook/1/issues -X 'POST' -d
'{"board_key":"DLK","url":"","issue_key":"DLK-1234","title":"a feature from
DLK","description":"","epic_key":"","type":"BUG","status":"TODO","original_status":"created","story_point":0,"resolution_date":null,"created_date":"2020-01-01T12:00:00+00:00","updated_date":null,"lead_time_minutes":0,"parent_issue_key":"DLK-1200","priority":"","original_estimate_minutes":0,"time_spent_minutes":0,"time_remaining_minutes":0,"crea
[...]
+curl https://sample-url.com/api/plugins/webhook/1/issues -X 'POST' -d
'{"url":"","issue_key":"DLK-1234","title":"a feature from
DLK","description":"","epic_key":"","type":"BUG","status":"TODO","original_status":"created","story_point":0,"resolution_date":null,"created_date":"2020-01-01T12:00:00+00:00","updated_date":null,"lead_time_minutes":0,"parent_issue_key":"DLK-1200","priority":"","original_estimate_minutes":0,"time_spent_minutes":0,"time_remaining_minutes":0,"creator_id":"user1131"
[...]
```
Sample CURL for Issue Closing:
```
-curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK/DLK-1234/close -X
'POST'
+curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK-1234/close -X 'POST'
```
## References
diff --git a/static/img/ConfigUI/project-webhook-use.png
b/static/img/ConfigUI/project-webhook-use.png
new file mode 100644
index 0000000000..c4a3a76b2a
Binary files /dev/null and b/static/img/ConfigUI/project-webhook-use.png differ
diff --git a/static/img/ConfigUI/project1.png b/static/img/ConfigUI/project1.png
new file mode 100644
index 0000000000..6b1a6dfee3
Binary files /dev/null and b/static/img/ConfigUI/project1.png differ
diff --git a/static/img/ConfigUI/webhook-connection.png
b/static/img/ConfigUI/webhook-connection.png
new file mode 100644
index 0000000000..c7abe29e17
Binary files /dev/null and b/static/img/ConfigUI/webhook-connection.png differ
diff --git a/static/img/ConfigUI/webhook-use.png
b/static/img/ConfigUI/webhook-use.png
deleted file mode 100644
index 88a3866caa..0000000000
Binary files a/static/img/ConfigUI/webhook-use.png and /dev/null differ
diff --git a/versioned_docs/version-v0.15/UserManuals/ConfigUI/webhook.md
b/versioned_docs/version-v0.15/UserManuals/ConfigUI/webhook.md
index 9616feab99..7f825e1bdc 100644
--- a/versioned_docs/version-v0.15/UserManuals/ConfigUI/webhook.md
+++ b/versioned_docs/version-v0.15/UserManuals/ConfigUI/webhook.md
@@ -14,11 +14,17 @@ Go to the 'Data Connections' page. Create a webhook.
We recommend that you give your webhook connection a unique name so that you
can identify and manage where you have used it later.
-### Step 2 - Use Webhooks
+### Step 2 - Create webhooks connection
-Click on Generate POST URL, and you will find four webhook URLs. Copy the ones
that suit your usage into your CI or issue-tracking systems. You can always
come back to the webhook page to copy the URLs later on.
+Click on Generate POST URL, and you will find three webhook URLs. Copy the
ones that suit your usage into your CI or issue-tracking systems. You can
always come back to the webhook page to copy the URLs later on.
-
+
+
+### Step 3 - Use webhook in a project
+
+Create a Project first, choose Incoming Webhooks, then you can `Add a Webhook`
or `Select Existing Webhooks`.
+
+
#### Put webhook on the internet
diff --git a/versioned_docs/version-v0.15/UserManuals/DORA.md
b/versioned_docs/version-v0.15/UserManuals/DORA.md
index 54c1a0d774..5d441066b7 100644
--- a/versioned_docs/version-v0.15/UserManuals/DORA.md
+++ b/versioned_docs/version-v0.15/UserManuals/DORA.md
@@ -5,47 +5,49 @@ description: >
DORA Metrics
---
-
This document describes everything you need to know about DORA, and
implementing this powerful and practical framework in DevLake.
## What are DORA metrics?
+
Created six years ago by a team of researchers, DORA stands for "DevOps
Research & Assessment" and is the answer to years of research, having examined
thousands of teams, seeking a reliable and actionable approach to understanding
the performance of software development teams.
DORA has since become a standardized framework focused on the stability and
velocity of development processes, one that avoids the more controversial
aspects of productivity and individual performance measures.
-There are two key clusters of data inside DORA: Velocity and Stability. The
DORA framework is focused on keeping them in context with each other, as a
whole, rather than as independent variables, making the data more challenging
to misinterpret or abuse.
+There are two key clusters of data inside DORA: Velocity and Stability. The
DORA framework is focused on keeping them in context with each other, as a
whole, rather than as independent variables, making the data more challenging
to misinterpret or abuse.
-Within velocity are two core metrics:
-- [Deployment
Frequency](https://devlake.apache.org/docs/Metrics/DeploymentFrequency): Number
of successful deployments to production, how rapidly is your team releasing to
users?
-- [Lead Time for
Changes](https://devlake.apache.org/docs/Metrics/LeadTimeForChanges): How long
does it take from commit to the code running in production? This is important,
as it reflects how quickly your team can respond to user requirements.
+Within velocity are two core metrics:
+
+- [Deployment Frequency](../Metrics/DeploymentFrequency): Number of successful
deployments to production, how rapidly is your team releasing to users?
+- [Lead Time for Changes](../Metrics/LeadTimeForChanges): How long does it
take from commit to the code running in production? This is important, as it
reflects how quickly your team can respond to user requirements.
Stability is composed of two core metrics:
-- [Median Time to Restore
Service](https://devlake.apache.org/docs/Metrics/MTTR): How long does it take
the team to properly recover from a failure once it is identified?
-- [Change Failure Rate](https://devlake.apache.org/docs/Metrics/CFR): How
often are your deployments causing a failure?
+
+- [Median Time to Restore Service](../Metrics/MTTR): How long does it take the
team to properly recover from a failure once it is identified?
+- [Change Failure Rate](../Metrics/CFR): How often are your deployments
causing a failure?
-To make DORA even more actionable, there are well-established benchmarks to
determine if you are performing at "Elite", "High", "Medium", or "Low" levels.
Inside DevLake, you will find the benchmarking table available to assess and
compare your own projects.
+To make DORA even more actionable, there are well-established benchmarks to
determine if you are performing at "Elite", "High", "Medium", or "Low" levels.
Inside DevLake, you will find the benchmarking table available to assess and
compare your own projects.
## Why is DORA important?
-DORA metrics help teams and projects measure and improve software development
practices to consistently deliver reliable products, and thus happy users!
+DORA metrics help teams and projects measure and improve software development
practices to consistently deliver reliable products, and thus happy users!
## How to implement DORA metrics with Apache DevLake?
You can set up DORA metrics in DevLake in a few steps:
-- **Install**: [Getting
Started](https://devlake.apache.org/docs/GettingStarted)
+
+- **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.
+ - 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 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.
-If your CI/CD tools are not listed on the [Supported Data
Sources](https://devlake.apache.org/docs/SupportedDataSources) page, have no
fear! DevLake provides incoming webhooks to push your `deployments` data to
DevLake. The webhook configuration doc can be found
[here](https://devlake.apache.org/docs/UserManuals/ConfigUI/webhook/).
-
+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](../UserManuals/ConfigUI/webhook/).
## A real-world example
@@ -64,113 +66,121 @@ Calculating DORA metrics requires three key entities:
**changes**, **deployments
In the next section, we'll demonstrate how to configure DevLake to implement
DORA metrics for the aforementioned example team.
### Collect GitHub & Jira data via `blueprint`
+
1. Visit the config-ui at `http://localhost:4000`
-2. Create a `blueprint`, let's name it "Blueprint for DORA", add a Jira and a
GitHub connection. Click `Next Step`
-
+2. Create a project: project1. Go to project1 and create a blueprint, let's
name it "Blueprint for DORA", add a Jira and a GitHub connection. Click `Next
Step`
+ 
+ 
3. Select Jira boards and GitHub repos to collect, click `Next Step`
-
+ 
4. Click `Add Transformation` to configure for DORA metrics
-
+ 
5. To make it simple, fields with a  label
are DORA-related configurations for every data source. Via these fields, you
can define what are "incidents" and "deployments" for each data source. After
all data connections have been configured, click `Next Step`
+
- This team uses Jira issue types `Crash` and `Incident` as "incident", so
choose the two types in field "incident". Jira issues in these two types will
be transformed to "incidents" in DevLake.
- This team uses the GitHub action jobs named `deploy` and
`build-and-deploy` to deploy, so type in `(?i)deploy` to match these jobs.
These jobs will be transformed to "deployments" in DevLake.
- 
-
+ 
+
Note: The following example shows where to find GitHub action jobs. It's
easy to mix them up with GitHub workflows.
-
6. Choose sync frequency, click 'Save and Run Now' to start data collection.
The time to completion varies by data source and depends on the volume of data.
-
+ 
-For more details, please refer to our [blueprint
manuals](https://devlake.apache.org/docs/UserManuals/ConfigUI/Tutorial).
+For more details, please refer to our [blueprint
manuals](../UserManuals/ConfigUI/Tutorial).
### 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. Visit "Data Connections" page in config-ui and select "Issue/Deployment
Incoming Webhook".
+7. Go to the 'Data Connections' page. Create a webhook.
+
+
+We recommend that you give your webhook connection a unique name so that you
can identify and manage where you have used it later.
-8. Click "Add Incoming Webhook", give it a name, and 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.
-
-
+8. Create a Project first, choose Incoming Webhooks, then you can `Add a
Webhook` or `Select Existing Webhooks`. And 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](https://devlake.apache.org/docs/Plugins/webhook/##register-a-deployment).
- ```
- version: 2.1
-
- jobs:
- build:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "build"
- command: |
- echo Hello, World!
-
- deploy:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "deploy"
- command: |
- # The time a deploy started
- start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
-
- # Some deployment tasks here ...
- echo Hello, World!
-
- # Send the request to DevLake after deploy
- # The values start with a '$CIRCLE_' are CircleCI's built-in
variables
- curl https://sample-url.com/api/plugins/webhook/1/deployments -X
'POST' -d "{
- \"commit_sha\":\"$CIRCLE_SHA1\",
- \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
- \"start_time\":\"$start_time\"
- }"
-
- workflows:
- build_and_deploy_workflow:
- jobs:
- - build
- - deploy
- ```
- If you have set a
[username/password](https://devlake.apache.org/docs/UserManuals/Authentication)
for Config UI, you need to add them to the curl to register a deployment:
-
- ```
- curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u
'username:password' -d '{
- \"commit_sha\":\"$CIRCLE_SHA1\",
- \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
- \"start_time\":\"$start_time\"
- }'
- ```
+ 
+
+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).
+
+```
+version: 2.1
+
+jobs:
+ build:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "build"
+ command: |
+ echo Hello, World!
+
+ deploy:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "deploy"
+ command: |
+ # The time a deploy started
+ start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
+
+ # Some deployment tasks here ...
+ echo Hello, World!
+
+ # Send the request to DevLake after deploy
+ # The values start with a '$CIRCLE_' are CircleCI's built-in
variables
+ curl http://127.0.0.1:4000/api/plugins/webhook/1/deployments -X
'POST' -d "{
+ \"commit_sha\":\"$CIRCLE_SHA1\",
+ \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
+ \"start_time\":\"$start_time\"
+ }"
+
+workflows:
+ build_and_deploy_workflow:
+ jobs:
+ - build
+ - deploy
+```
+
+If you have set a [username/password](../GettingStarted/Authentication) for
Config UI, you need to add them to the curl to register a deployment:
+
+```
+curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u
'username:password' -d '{
+ \"commit_sha\":\"$CIRCLE_SHA1\",
+ \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
+ \"start_time\":\"$start_time\"
+ }'
+```
11. Run the modified CircleCI pipeline. Check to verify that the request has
been successfully sent.
-
+ 
12. You will find the corresponding `deployments` in table.cicd_tasks in
DevLake's database.
-
+ 
-### 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. 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.
For a breakdown of each metric's SQL query, please refer to the corresponding
metric docs:
- - [Deployment
Frequency](https://devlake.apache.org/docs/Metrics/DeploymentFrequency)
- - [Lead Time for
Changes](https://devlake.apache.org/docs/Metrics/LeadTimeForChanges)
- - [Median Time to Restore
Service](https://devlake.apache.org/docs/Metrics/MTTR)
- - [Change Failure Rate](https://devlake.apache.org/docs/Metrics/CFR)
+
+- [Deployment Frequency](../Metrics/DeploymentFrequency)
+- [Lead Time for Changes](../Metrics/LeadTimeForChanges)
+- [Median Time to Restore Service](../Metrics/MTTR)
+- [Change Failure Rate](../Metrics/CFR)
If you aren't familiar with Grafana, please refer to our [Grafana
doc](./Dashboards/GrafanaUserGuide.md), or jump into Slack for help.
