1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
This document explains how to get GitHub webhooks (a notification that an
event such as a push has occurred on a repository) delivered to a
locally-running instance of brep (currently to initiate a CI job).
0. Overview of the brep GitHub CI integration
First we register our GitHub CI brep instance as a GitHub app. This GitHub app
essentially consists of an app name, the URL we want webhooks to be delivered
to, permissions required on users' repositories, event subscriptions, and
various authentication-related settings.
Once registered, GitHub users can install this GitHub app on their user's or
organization's accounts, optionally restricting its access to specific
repositories.
Once installed on a repository, GitHub will send webhook requests to our app's
webhook URL when, for example, code is pushed or a pull request is created
(the specifics depending on the events our app is subscribed to).
For development we need these webhooks delivered to our locally-running brep
instance. This is achieved by setting the GitHub app's webhook URL to that of
the webhook proxy smee.io (as recommended by GitHub) and connecting it to our
local brep instance via the locally-run smee client (a Node application).
0.0 User configuration
This GitHub CI integration only has one user-configurable option:
warning=<success|failure> (whether or not to fail on warnings).
In order not to have to support repository configuration files the live
deployment will consist of two registered GitHub apps with the same webhook
URL (i.e., the same brep instance) but different query parameters: one with
warning=success and the other with warning=failure. The app id is passed so
that we know which private key to use (the key cannot be shared between apps).
Only a single GitHub app is required during development however.
1. Follow the instructions in INSTALL-DEV to get brep set up.
2. Set up the webhook proxy
Go to https://smee.io/ and start a new channel. Note the webhook proxy URL,
which will look something like
https://smee.io/7stvNqVgyQRlIhbY
This will be used in the GitHub app's webhook URL below.
3. Register the GitHub app
GitHub reference: Registering a GitHub App (note: somewhat out of date)
https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app
At this stage the only settings we need to update are:
- App name
- Homepage URL (https://build2.org)
- Webhook
- URL: set to the webhook proxy URL
- Secret (e.g. "deadbeef")
- Leave SSL verification enabled
- Repository permissions
- Checks: RW
- Metadata (mandatory): RO
- Pull requests: RO
- Contents: RO (for Push events)
- Subscribed events
- Check suite
- Pull request
- Push
Click "Create GitHub App" button. When the page reloads:
- Note the app id (e.g. 12345).
- Append "?app-id=12345&warning=failure" to the webhook URL.
- Scroll to Private keys and generate a private key. The file will be
downloaded by the browser.
4. Install the GitHub app
GitHub doc: Installing your own GitHub App
https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app
It would probably make sense to install it to your own user account and
restrict its access to a test repository.
5. Configure brep
In brep-module.conf:
- Set the webhook secret from the GitHub app settings:
ci-github-app-webhook-secret "deadbeef"
- Associate the GitHub app id with the path of the private key downloaded
above:
ci-github-app-id-private-key 12345=path/to/private-key.pem
6. Forward GitHub webhooks to a local brep instance
Install the smee client:
$ npm install --global smee-client
Start brep.
Start the smee client, passing the webhook proxy URL with --url and the brep
GitHub CI endpoint's URL with --target:
$ smee --url https://smee.io/7stvNqVgyQRlIhbY \
--target http://127.0.0.1/pkg?ci-github
Trigger a webhook delivery from GitHub by pushing a commit to a repository the
GitHub app is installed in. You should see the webhook delivery on the smee.io
channel page.
A webhook can be redelivered from the smee.io channel page or the app's
advanced settings page on GitHub so no need to repeatedly push to the
repository.
Both the smee.io channel and the GitHub app's advanced settings show the JSON
payloads of delivered webhooks. smee.io's presentation is better but the
GitHub app page also shows the HTTP headers. Wireshark might be better in both
aspects but can't redeliver webhooks.
7. Test scenarios
- Branch push (BP).
- Success (observe check runs state transitions). Test with 2 build configs.
- Failure (observe check runs state transitions).
- Push new commit to branch.
- Re-requested check suite.
- Re-requested check run (observe check run state transitions).
- Re-requested check run but tenant archived.
- Cancel previous check suite on forced push.
- Head commit shared with another BP.
- Cancel previous check suite on forced push with shared previous commit.
- Pull request (PR).
- Local PR.
- Success.
- Failure.
- Push new commit to head.
- Re-requested check suite.
- Re-requested check run.
- Head shared with BP.
- Not meargeable/head behind base.
- Remote PR.
- Success.
- Failure.
- Push new commit to head.
- Re-requested check suite.
- Re-requested check run.
- Head shared with another remote PR.
- Cancel previous check suite on head move.
|
