You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`--app-id`|`APP_ID`|| GitHub app ID of the bors bot. |
20
-
|`--private-key`|`PRIVATE_KEY`|| Private key of the GitHub app. |
21
-
|`--webhook-secret`|`WEBHOOK_SECRET`|| Key used to authenticate GitHub webhooks. |
22
-
|`--client-id`|`OAUTH_CLIENT_ID`|| GitHub OAuth client ID for rollup UI (optional). |
23
-
|`--client-secret`|`OAUTH_CLIENT_SECRET`|| GitHub OAuth client secret for rollup UI (optional). |
24
-
|`--db`|`DATABASE_URL`|| Database connection string. Only PostgreSQL is supported. |
25
-
|`--cmd-prefix`|`CMD_PREFIX`|@bors| Prefix used to invoke bors commands in PR comments. |
26
-
|`--web_url`|`WEB_URL`|http://localhost:8080| Web URL where the bot's website is deployed (optional).|
27
-
|`--permissions`|`PERMISSIONS`| Rust Team API url| Either a URL to the team v1 API or a path to a directory containing JSON files with try/review permissions (optional).|
|`--app-id`|`APP_ID`|| GitHub app ID of the bors bot.|
20
+
|`--private-key`|`PRIVATE_KEY`|| Private key of the GitHub app.|
21
+
|`--webhook-secret`|`WEBHOOK_SECRET`|| Key used to authenticate GitHub webhooks.|
22
+
|`--client-id`|`OAUTH_CLIENT_ID`|| GitHub OAuth client ID for rollup UI (optional).|
23
+
|`--client-secret`|`OAUTH_CLIENT_SECRET`|| GitHub OAuth client secret for rollup UI (optional).|
24
+
|`--db`|`DATABASE_URL`|| Database connection string. Only PostgreSQL is supported.|
25
+
|`--cmd-prefix`|`CMD_PREFIX`|@bors| Prefix used to invoke bors commands in PR comments.|
26
+
|`--web_url`|`WEB_URL`|http://localhost:8080| Web URL where the bot's website is deployed (optional).|
27
+
|`--permissions`|`PERMISSIONS`| Rust Team API URL | Either a URL to the team v1 API or a path to a directory containing JSON files with try/review permissions (optional).|
28
28
29
29
### Special branches
30
30
The bot uses the following branch names for its operations.
Copy file name to clipboardExpand all lines: docs/development.md
+71-65Lines changed: 71 additions & 65 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,14 @@
2
2
This document should help you make sense of the codebase and provide
3
3
guidance on working with it and testing it locally.
4
4
5
+
Note that since Bors is a GitHub app, it has a relatively non-trivial first-time
6
+
setup that is required to test it on live repositories. You don't *need* to do that
7
+
though, as we also have a comprehensive integration test suite, which should be enough
8
+
to test most changes.
9
+
5
10
Directory structure:
6
11
-`migrations`
7
-
-`sqlx` migrations that are the source of truth for database schema
12
+
-`sqlx` migrations that are the source of truth for database schema.
8
13
-`src/bors`
9
14
- Bors commands and their handlers.
10
15
-`src/database`
@@ -13,7 +18,7 @@ Directory structure:
13
18
- Communication with the GitHub API and definitions of GitHub webhook messages.
14
19
15
20
## Architecture diagram
16
-
The following diagram shows a simplified view on the important state entities of Bors. `bors_process` handles events generated by webhooks. It uses a shared global state through `BorsContext`, which holds a shared connection to the database and a command parser. It also has access to a map of repository state. Each repository state contains an API client for that repository, its loaded config, and permissions loaded from the Team API.
21
+
The following diagram shows a simplified view on the important state entities of Bors. `bors_process` handles events generated by webhooks. It uses a shared global state through `BorsContext`, which holds a shared connection to the database and a command parser. It also has access to a map of repository states. Each repository state contains an API client for that repository, its loaded config, and permissions loaded from the Team API.
17
22
18
23
```mermaid
19
24
---
@@ -41,63 +46,6 @@ flowchart
41
46
bors_process --> BorsContext
42
47
```
43
48
44
-
## How to test bors on live repositories
45
-
Bors has a `cargo` test suite that you can run locally, but sometimes nothing beats an actual test on live, GitHub
46
-
repositories. The bot has a staging deployment at the https://github.com/rust-lang/bors-kindergarten repository,
47
-
where you can try it however you want.
48
-
49
-
Nevertheless, sometimes it might be easier to test it on your own repository. The process is a bit involved, but it
50
-
can still be done if needed.
51
-
52
-
One-time setup:
53
-
- Create your own GitHub app.
54
-
- Configure its webhook secret.
55
-
- Configure its private key.
56
-
- Give it permissions for `Actions` (r/w), `Checks` (r/w), `Contents` (r/w), `Issues` (r/w) and `Pull requests` (r/w).
57
-
- Subscribe it to webhook events `Issue comment`, `Pull request`, `Pull request review`, `Pull request review comment` and `Workflow run`.
58
-
- Install your GitHub app on some test repository where you want to test bors.
59
-
- Don't forget to configure `rust-bors.toml` in the root of the repository, and also add some example CI workflows.
60
-
- Create try/review permissions for Github users
61
-
- Copy a review json file `cp data/permissions/bors.review.json.example data/permissions/bors.review.json`
62
-
- Copy a try json file `cp data/permissions/bors.try.json.example data/permissions/bors.try.json`
63
-
- Get your Github user `ID``https://api.github.com/users/<your_github_user_name>`
64
-
- Edit both `bors.review.json` and `bors.try.json` files to include your GitHub `ID`: `{ "github_ids": [12345678] }`
65
-
66
-
Everytime you want to run bors:
67
-
- Run bors locally.
68
-
- Set `APP_ID` to the ID of the app
69
-
- Set `WEBHOOK_SECRET` to the webhook secret of the app.
70
-
- Set `PRIVATE_KEY` to the private key of the app.
71
-
- (optional) Set `WEB_URL` to the public URL of the website of the app.
72
-
- (optional) Set `CMD_PREFIX` to the command prefix used to control the bot (e.g. `@bors`).
73
-
- (optional) Set `PERMISSIONS``"data/permissions"` directory path to list users with permissions to perform try/review.
74
-
- Set up some globally reachable URL/IP address for your computer, e.g. using [ngrok](https://ngrok.com/).
75
-
- Configure the webhook URL for your app to point to `<address>/github`. You can use [gh webhook](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing) for that.
76
-
- Try `@bors ping` on some PR on the test repository :)
77
-
78
-
## Seeding
79
-
For testing the merge queue, there's a `scripts/seed.py` script that can automatically create multiple PRs and approve them with `@bors r+` command.
80
-
81
-
### Prerequisites
82
-
```console
83
-
$ pip install PyGithub
84
-
```
85
-
86
-
### Usage
87
-
The script requires a GitHub personal access token with the following permissions:
@@ -139,20 +88,77 @@ Make sure to also run `cargo sqlx migrate run` to apply the migrations to the da
139
88
$ cargo sqlx migrate run
140
89
```
141
90
4) Add a test data file to `tests/data/migrations/<timestamp>-<new-migration>.sql`.
142
-
- The file should contain SQL that inserts some reasonable data into a test database after the migration is applied.
91
+
- The file should contain SQL that inserts some reasonable data into a test database after the migration is applied.
143
92
The goal is to check that we have a test database with production-like data, so that we can test that applying migrations will not produce errors on a non-empty database.
144
-
- If it doesn't make sense to add any data to the migration (e.g. if the migration only adds an index), put `-- Empty to satisfy migration tests` into the file.
93
+
- If it doesn't make sense to add any data to the migration (e.g. if the migration only adds an index), put `-- Empty to satisfy migration tests` into the file.
145
94
146
95
### Regenerate `.sqlx` directory
96
+
Before you make a commit that changes SQL queries in the bors codebase, you should regenerate the stored `sqlx` metadata files in the `.sqlx` directory:
97
+
147
98
```console
148
99
$ rm -rf .sqlx
149
100
$ cargo sqlx prepare -- --all-targets
150
101
$ git add .sqlx
151
102
```
152
103
153
-
After that, you should commit the changes to the `.sqlx` directory.
104
+
> Make sure to remove the `.sqlx` directory before running the `prepare` command, to ensure that leftover queries do not remain committed in the repository.
105
+
106
+
## How to test bors on live repositories
107
+
Bors has a `cargo` test suite that you can run locally, but sometimes nothing beats an actual test on live, GitHub
108
+
repositories. The bot has a staging deployment at the https://github.com/rust-lang/bors-kindergarten repository,
109
+
where you can try it however you want.
110
+
111
+
Nevertheless, sometimes it might be easier to test it on your own repository. The process is a bit involved, but it
112
+
can still be done if needed.
113
+
114
+
### One-time setup
115
+
- Create your own [GitHub app](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
116
+
- Configure its webhook secret and private key and write them down.
117
+
- Give it permissions for `Actions` (r/w), `Checks` (r/w), `Contents` (r/w), `Issues` (r/w) and `Pull requests` (r/w).
118
+
- Subscribe it to webhook events `Issue comment`, `Pull request`, `Pull request review`, `Pull request review comment` and `Workflow run`.
119
+
- Install your GitHub app on some test repository where you want to test bors.
120
+
- Add `rust-bors.toml` in the root of the repository, and also add some example CI workflows.
121
+
- Create try/review permissions for GitHub users
122
+
- Copy a review JSON file `cp data/permissions/bors.review.json.example data/permissions/bors.review.json`
123
+
- Copy a try JSON file `cp data/permissions/bors.try.json.example data/permissions/bors.try.json`
124
+
- Get your GitHub user `ID``https://api.github.com/users/<your_github_user_name>`
125
+
- Edit both `bors.review.json` and `bors.try.json` files to include your GitHub `ID`: `{ "github_ids": [12345678] }`
126
+
127
+
### Everytime you run bors
128
+
1. Start the Postgres [database](#Database)
129
+
2. Run bors locally, and configure environment variables and/or command-line parameters for it:
130
+
- Set `APP_ID` to the ID of the created GitHub app.
131
+
- Set `WEBHOOK_SECRET` to the webhook secret of the app.
132
+
- Set `PRIVATE_KEY` to the private key of the app.
133
+
- (optional) Set `WEB_URL` to the public URL of the website of the app.
134
+
- (optional) Set `CMD_PREFIX` to the command prefix used to control the bot (e.g. `@bors`).
135
+
- (optional) Set `PERMISSIONS``"data/permissions"` directory path to list users with permissions to perform try/review.
136
+
3. Redirect webhooks from your test repository to bors. You can [gh webhook](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing) for that.
137
+
- If you want to do it manually, you need to configure a globally reachable URL/IP address for your computer e.g. using [ngrok](https://ngrok.com/), and then configure the webhook URL of your GitHub app to point to `<your-pc-address>/github`.
138
+
4. Try `@bors ping` on some PR on your test repository :)
139
+
140
+
## Seeding test repositories
141
+
For testing the merge queue, there's a `scripts/seed.py` script that can automatically create multiple PRs on a given repository and approve them with `@bors r+` command.
142
+
143
+
### Prerequisites
144
+
```console
145
+
$ pip install PyGithub
146
+
```
147
+
148
+
### Usage
149
+
The script requires a GitHub personal access token with the following permissions:
150
+
-**Contents** (read/write)
151
+
-**Pull requests** (read/write)
152
+
-**Issues** (write)
154
153
155
-
Make sure to remove the `.sqlx` directory before running the `prepare` command, to ensure that leftover queries are not do not remain committed to the repository.
0 commit comments