debian-mirror-gitlab/doc/development/dangerbot.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

207 lines
9.4 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2019-12-04 20:38:33 +05:30
# Danger bot
2020-04-22 19:07:51 +05:30
The GitLab CI/CD pipeline includes a `danger-review` job that uses [Danger](https://github.com/danger/danger)
2019-12-04 20:38:33 +05:30
to perform a variety of automated checks on the code under test.
Danger is a gem that runs in the CI environment, like any other analysis tool.
2021-02-22 17:27:13 +05:30
What sets it apart from (for example, RuboCop) is that it's designed to allow you to
2019-12-04 20:38:33 +05:30
easily write arbitrary code to test properties of your code or changes. To this
end, it provides a set of common helpers and access to information about what
has actually changed in your environment, then simply runs your code!
If Danger is asking you to change something about your merge request, it's best
just to make the change. If you want to learn how Danger works, or make changes
to the existing rules, then this is the document for you.
2020-04-08 14:13:33 +05:30
## Danger comments in merge requests
Danger only posts one comment and updates its content on subsequent
`danger-review` runs. Given this, it's usually one of the first few comments
in a merge request if not the first. If you didn't see it, try to look
from the start of the merge request.
### Advantages
- You don't get email notifications each time `danger-review` runs.
### Disadvantages
2021-02-22 17:27:13 +05:30
- It's not obvious Danger updates the old comment, thus you need to
2020-04-08 14:13:33 +05:30
pay attention to it if it is updated or not.
2020-03-13 15:44:24 +05:30
## Run Danger locally
2020-04-22 19:07:51 +05:30
A subset of the current checks can be run locally with the following Rake task:
2020-03-13 15:44:24 +05:30
```shell
bin/rake danger_local
```
2019-12-04 20:38:33 +05:30
## Operation
2021-09-04 01:27:46 +05:30
On startup, Danger reads a [`Dangerfile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/Dangerfile)
2021-02-22 17:27:13 +05:30
from the project root. Danger code in GitLab is decomposed into a set of helpers
2019-12-04 20:38:33 +05:30
and plugins, all within the [`danger/`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/danger/)
2021-02-22 17:27:13 +05:30
subdirectory, so ours just tells Danger to load it all. Danger then runs
2019-12-04 20:38:33 +05:30
each plugin against the merge request, collecting the output from each. A plugin
may output notifications, warnings, or errors, all of which are copied to the
2021-02-22 17:27:13 +05:30
CI job's log. If an error happens, the CI job (and so the entire pipeline) fails.
2019-12-04 20:38:33 +05:30
2021-02-22 17:27:13 +05:30
On merge requests, Danger also copies the output to a comment on the MR
2019-12-04 20:38:33 +05:30
itself, increasing visibility.
## Development guidelines
2021-09-30 23:02:18 +05:30
Danger code is Ruby code, so all our [usual backend guidelines](index.md#backend-guides)
2019-12-04 20:38:33 +05:30
continue to apply. However, there are a few things that deserve special emphasis.
### When to use Danger
Danger is a powerful tool and flexible tool, but not always the most appropriate
way to solve a given problem or workflow.
2022-07-16 23:28:13 +05:30
First, be aware of the GitLab [commitment to dogfooding](https://about.gitlab.com/handbook/engineering/development/principles/#dogfooding).
2019-12-04 20:38:33 +05:30
The code we write for Danger is GitLab-specific, and it **may not** be most
appropriate place to implement functionality that addresses a need we encounter.
Our users, customers, and even our own satellite projects, such as [Gitaly](https://gitlab.com/gitlab-org/gitaly),
2020-05-24 23:13:21 +05:30
often face similar challenges, after all. Think about how you could fulfill the
2019-12-04 20:38:33 +05:30
same need while ensuring everyone can benefit from the work, and do that instead
if you can.
2021-02-22 17:27:13 +05:30
If a standard tool (for example, `rubocop`) exists for a task, it's better to
use it directly, rather than calling it by using Danger. Running and debugging
the results of those tools locally is easier if Danger isn't involved, and
unless you're using some Danger-specific functionality, there's no benefit to
including it in the Danger run.
2019-12-04 20:38:33 +05:30
Danger is well-suited to prototyping and rapidly iterating on solutions, so if
what we want to build is unclear, a solution in Danger can be thought of as a
trial run to gather information about a product area. If you're doing this, make
sure the problem you're trying to solve, and the outcomes of that prototyping,
2021-02-22 17:27:13 +05:30
are captured in an issue or epic as you go along. This helps us to address
2019-12-04 20:38:33 +05:30
the need as part of the product in a future version of GitLab!
### Implementation details
Implement each task as an isolated piece of functionality and place it in its
own directory under `danger` as `danger/<task-name>/Dangerfile`.
Each task should be isolated from the others, and able to function in isolation.
If there is code that should be shared between multiple tasks, add a plugin to
`danger/plugins/...` and require it in each task that needs it. You can also
create plugins that are specific to a single task, which is a natural place for
complex logic related to that task.
Danger code is just Ruby code. It should adhere to our coding standards, and
needs tests, like any other piece of Ruby in our codebase. However, we aren't
able to test a `Dangerfile` directly! So, to maximize test coverage, try to
minimize the number of lines of code in `danger/`. A non-trivial `Dangerfile`
should mostly call plugin code with arguments derived from the methods provided
by Danger. The plugin code itself should have unit tests.
2021-03-11 19:13:27 +05:30
At present, we do this by putting the code in a module in `tooling/danger/...`,
2019-12-04 20:38:33 +05:30
and including it in the matching `danger/plugins/...` file. Specs can then be
2021-03-11 19:13:27 +05:30
added in `spec/tooling/danger/...`.
2019-12-04 20:38:33 +05:30
2021-02-22 17:27:13 +05:30
To determine if your `Dangerfile` works, push the branch that contains it to
GitLab. This can be quite frustrating, as it significantly increases the cycle
time when developing a new task, or trying to debug something in an existing
one. If you've followed the guidelines above, most of your code can be exercised
locally in RSpec, minimizing the number of cycles you need to go through in CI.
However, you can speed these cycles up somewhat by emptying the
2019-12-04 20:38:33 +05:30
`.gitlab/ci/rails.gitlab-ci.yml` file in your merge request. Just don't forget
to revert the change before merging!
2021-12-11 22:18:48 +05:30
#### Adding labels via Danger
NOTE:
2022-05-07 20:08:51 +05:30
This is applicable to all the projects that use the [`gitlab-dangerfiles` gem](https://rubygems.org/gems/gitlab-dangerfiles).
2021-12-11 22:18:48 +05:30
Danger is often used to improve MR hygiene by adding labels. Instead of calling the
2022-05-07 20:08:51 +05:30
API directly in your `Dangerfile`, add the labels to `helper.labels_to_add` array (with `helper.labels_to_add << label`
or `helper.labels_to_add.concat(array_of_labels)`.
`gitlab-dangerfiles` will then take care of adding the labels to the MR with a single API call after all the rules
have had the chance to add to `helper.labels_to_add`.
2021-12-11 22:18:48 +05:30
#### Shared rules and plugins
If the rule or plugin you implement can be useful for other projects, think about
2022-01-26 12:08:38 +05:30
upstreaming them to the [`gitlab-dangerfiles`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-dangerfiles) project.
2021-12-11 22:18:48 +05:30
#### Enable Danger on a project
2022-05-07 20:08:51 +05:30
To enable the Dangerfile on another existing GitLab project, complete the following steps:
2020-01-01 13:55:28 +05:30
2022-05-07 20:08:51 +05:30
1. Add [`gitlab-dangerfiles`](https://rubygems.org/gems/gitlab-dangerfiles) to your `Gemfile`.
1. Create a `Dangerfile` with the following content:
```ruby
2022-06-21 17:19:12 +05:30
require "gitlab-dangerfiles"
2022-05-07 20:08:51 +05:30
Gitlab::Dangerfiles.for_project(self, &:import_defaults)
```
1. Add the following to your CI/CD configuration:
```yaml
include:
- project: 'gitlab-org/quality/pipeline-common'
file:
- '/ci/danger-review.yml'
2022-06-21 17:19:12 +05:30
rules:
2022-07-16 23:28:13 +05:30
- if: $CI_SERVER_HOST == "gitlab.com"
2022-05-07 20:08:51 +05:30
```
1. If your project is in the `gitlab-org` group, you don't need to set up any token as the `DANGER_GITLAB_API_TOKEN`
variable is available at the group level. If not, follow these last steps:
1. Create a [Project access tokens](../user/project/settings/project_access_tokens.md).
1. Add the token as a CI/CD project variable named `DANGER_GITLAB_API_TOKEN`.
2020-01-01 13:55:28 +05:30
2021-09-30 23:02:18 +05:30
You should add the ~"Danger bot" label to the merge request before sending it
2019-12-04 20:38:33 +05:30
for review.
## Current uses
Here is a (non-exhaustive) list of the kinds of things Danger has been used for
at GitLab so far:
- Coding style
2020-07-28 23:09:34 +05:30
- Database review
- Documentation review
2019-12-04 20:38:33 +05:30
- Merge request metrics
2020-07-28 23:09:34 +05:30
- Reviewer roulette. Reviewers and maintainers are chosen based on:
- Their roles (backend, frontend, database, etc).
- Their availability:
- No "OOO"/"PTO"/"Parental Leave" in their GitLab or Slack status.
- No `:red_circle:`/`:palm_tree:`/`:beach:`/`:beach_umbrella:`/`:beach_with_umbrella:` emojis in GitLab or Slack status.
2021-11-18 22:05:49 +05:30
- (Experimental) Their time zone: people for which the local hour is between
2020-07-28 23:09:34 +05:30
6 AM and 2 PM are eligible to be picked. This is to ensure they have a good
chance to get to perform a review during their current work day. The experimentation is tracked in
[this issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/563)
2019-12-04 20:38:33 +05:30
- Single codebase effort
## Limitations
2021-04-29 21:17:54 +05:30
Danger is run but its output is not added to a merge request comment if working
on a fork. This happens because the secret variable from the canonical project
2021-10-27 15:23:28 +05:30
is not shared to forks.
### Configuring Danger for forks
Contributors can configure Danger for their forks with the following steps:
2022-07-16 23:28:13 +05:30
1. Create a [personal API token](https://gitlab.com/-/profile/personal_access_tokens?name=GitLab+Dangerbot&scopes=api)
that has the `api` scope set (don't forget to copy it to the clipboard).
1. In your fork, add a [project CI/CD variable](../ci/variables/index.md#add-a-cicd-variable-to-a-project)
called `DANGER_GITLAB_API_TOKEN` with the token copied in the previous step.
1. Make the variable [masked](../ci/variables/index.md#mask-a-cicd-variable) so it
doesn't show up in the job logs. The variable cannot be
[protected](../ci/variables/index.md#protected-cicd-variables), because it needs
to be present for all branches.