Skip to content

Commit d90c23d

Browse files
dregaddregad
committed
Update SourceGithub documentation
- detail the process of creating OAuth app - split instructions to create repository in sub-sections - add instructions to create the Webhook - minor changes Fixes #304
1 parent ded57a4 commit d90c23d

File tree

1 file changed

+149
-46
lines changed

1 file changed

+149
-46
lines changed

‎docs/CONFIGURING.SourceGithub.md‎

Lines changed: 149 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,77 +2,180 @@
22

33
## Description
44

5-
The **SourceGithub** extension plugin adds support for Git repositories
6-
hosted on [GitHub](http://github.com/), both public & private as well as
7-
personal & organization repositories.
5+
The **SourceGithub** extension plugin adds support for both public & private as
6+
well as personal & organization Git repositories hosted on
7+
[GitHub](http://github.com/).
88

99

1010
## Requirements
1111

12-
The **SourceGithub** plugin requires MantisBT version 2.3.0 or later. See the
12+
The **SourceGithub** plugin requires MantisBT version 2.3.0 or later. See the
1313
[README](../README.md#requirements) for further information.
1414

15-
Ensure both the **Source** and **SourceGithub** plugins are installed.
15+
Ensure both the **Source** and **SourceGithub** plugins are properly installed.
1616
See the [README](../README.md#installation) for overall instructions.
1717

1818

1919
## Configuration
2020

21+
### Create a GitHub OAuth App
22+
23+
Setting up an OAuth app is required to authenticate the Source Integration
24+
plugin and authorize it to access Private repositories.
25+
26+
It also allows increasing the GitHub API [Rate Limit](https://developer.github.com/v3/#rate-limiting)
27+
when importing changesets to 5'000 requests per hour. Unauthenticated requests
28+
are limited to 60 calls per hour, which would only be sufficient for very small
29+
repositories.
30+
31+
Finally, it facilitates the creation of a Webhook from within the plugin's
32+
repository management page, which lets GitHub trigger automatic import and
33+
processing of commits, as they are pushed to the repository.
34+
35+
1. Navigate to your [GitHub Developer settings](https://github.com/settings/developers) page
36+
37+
2. Click on the [New OAuth App](https://github.com/settings/applications/new) button
38+
39+
3. Fill in the form
40+
- Give a name to your app, e.g. `MantisBT Source Integration`
41+
- Set _Homepage URL_ as appropriate (e.g. point to your website or your
42+
MantisBT instance)
43+
- Provide an _Application description_ if necessary
44+
- _Authorization callback URL_ should point to your MantisBT instance's
45+
base URL, e.g. `https://path.to/mantis/`
46+
47+
4. Click on **Register application**
48+
49+
5. Take note of the generated _Client ID_ and _Client Secret_, you will need
50+
them later on
51+
52+
**NOTE:** a single OAuth app is sufficient to handle all the GitHub repositories
53+
configured in a given MantisBT instance.
54+
55+
56+
### Create a Repository
57+
2158
1. Click the *Repositories* link in the navigation bar.
2259

23-
2. In the *Create Repository* section:
60+
2. Fill the form in the *Create Repository* section:
61+
- Enter the repository's name in the *Name* text field
62+
- Select *GitHub* from the *Type* pop-up menu
63+
64+
3. Click the **Create Repository** button.
65+
66+
4. This will take you to the *Update Repository* page, where you'll need to fill
67+
in all the details for the repository:
68+
69+
- The *Name* will be pre-populated with whatever you entered in step 2 above.
70+
- Paste in the GitHub repository's URL in the *URL* field
71+
(e.g. `https://github.com/mantisbt-plugins/source-integration`).
72+
- Enter the name of the repository's owner in *GitHub Username*
73+
(e.g. `mantisbt-plugins`)
74+
- Enter the name of the GitHub repository in the *GitHub Repository Name*
75+
field (e.g. `source-integration`)
76+
- Paste the your OAuth app's _Client ID_ and _Client Secret_ in the
77+
GitHub Application Client ID and Secret fields
78+
- The _GitHub Webhook Secret_ is not mandatory, but provides additional
79+
security as it will allows the plugin to validate the payload received
80+
from the GitHub Webhook to ensure it's legit
81+
- By default, the *Primary Branches* is set to `master`, but you can specify
82+
another branch or additional ones (comma-separated), or use `*` for all
83+
branches
84+
85+
5. Click the **Update Repository** button to save your changes
86+
87+
88+
### Authorize the plugin to access GitHub
89+
90+
See the [Create a GitHub OAuth App section](#create-a-github-oauth-app) for an
91+
explanation of why this step is needed.
92+
93+
1. In the Update Repository page, next to _GitHub Application Access Token_,
94+
click the **Authorize** button
95+
96+
2. The plugin will redirect to a GitHub page asking for authorization to
97+
access your personal public and private reporitories, as well as the
98+
organizations you are a member of. Click **Authorize**
99+
100+
**NOTE:** Full access is requested, as GitHub does not allow fine-grained
101+
control over permissions for OAuth applications. However, the SourceGithub
102+
plugin will only:
103+
- read code (branches and commits)
104+
- create a _push_ event Webhook (see [below](#setup-the-webhook))
105+
106+
3. You will be redirected back to the SourceGithub plugin, where you should see
107+
a confirmation message informing you that authorization has been granted.
108+
109+
4. Click **Proceed**. This will take you back to the Update Repository page,
110+
where you should see _Authorized_ next to _GitHub Application Access Token_.
111+
112+
**NOTE:** You may revoke the authorization at any time by clicking on the
113+
_Update Repository_ page's **Revoke** button. Also, for obvious security
114+
reasons, the Token will automatically be deleted if the Client ID or Secret are
115+
changed.
116+
117+
118+
### Setup the Webhook
119+
120+
Use of a push event Webhook is strongly recommended, as it will let GitHub
121+
automatically trigger the processing of new commits, whenever they are pushed
122+
to the repository.
123+
124+
1. In the Update Repository page, next to _GitHub Webhook Secret_, click the
125+
**Create Webhook** button
24126

25-
- Enter the repository name in the *Name* text field.
26-
- Select *GitHub* from the *Type* pop-up menu.
27-
- Click the *Create Repository* button.
127+
2. You should see a confirmation message, indicating that the Webhook was
128+
created successfully. If not, an error message will be displayed, and you
129+
may find additional information about whatever prevented the operation to
130+
succeed in the browser's console.
28131

29-
3. This will take you to the *Update Repository* page where you'll need to fill
30-
in all the details for the repository:
132+
**NOTE:** The most common cause for failure is when the Webhook already
133+
exists, and could therefore not be created. In that case, the error message
134+
becomes a hyperlink, which will take you to the Webhook's config page on
135+
GitHub.
31136

32-
- The *Name* field should be pre-populated with the name you entered in Step 3a above.
137+
3. Click **Back to Repository**
33138

34-
- Paste in the GitHub repository's URL in the *URL* field
35-
(e.g. `https://github.com/mantisbt-plugins/source-integration`).
139+
If you prefer, it is also possible to setup the webhook manually:
36140

37-
- Enter the GitHub username of the repository's owner in the *GitHub Username*
38-
field (e.g. "mantisbt-plugins").
141+
1. Go to the repository's settings page (e.g. ), and select Webhooks
39142

40-
- Enter the GitHub repository's name in the *GitHub Repository Name* field
41-
(e.g. "source-integration").
143+
2. Click on **Add Webhook**
42144

43-
- If it's a public GitHub repository, you can skip the *GitHub Application
44-
Client ID* & *GitHub Application Secret* fields. If it's a private
45-
repository, you'll need to configure a GitHub Developer Application:
145+
3. Fill in the form
146+
- Set _Payload URL_ to
147+
`https://path.to/mantis/plugin.php?page=Source/checkin&api_key=XXXX`,
148+
where XXXX is your _API Key_, as defined in the Source Integration plugin's
149+
Configuration page.
150+
- _Content type_ must be set to `application/json`
151+
- _Secret_ must match the _GitHub Webhook Secret_ defined in step 4 of the
152+
[Create a Repository](#create-a-repository) section above
153+
- Select _Just the push event_
154+
- Make sure the _Active_ checkbox is checked
46155

47-
1. Visit https://github.com/settings/developers and click the *Register
48-
new application* button.
49-
2. Enter *MantisBT Source Integration* in the *Application name* field.
50-
3. Enter the URL for your Mantis installation in the *Homepage URL*
51-
field.
52-
4. Enter the URL for your Mantis Source/oauth page (the URL with
53-
`/plugin.php?page=Source/oauth` appended to it; e.g. "http://mantisbt.org/bugs/plugin.php?page=Source/oauth").
54-
5. Click the *Register application* button.
55-
6. Switch back to your Mantis GitHub Repository configuration.
56-
7. Enter your GitHub Developer Application's Client ID in the *GitHub
57-
Application Client ID* field.
58-
8. Enter your GitHub Developer Application's Secret in the *GitHub
59-
Application Access Secret* field.
156+
4. Click on **Add Webhook**
60157

61-
- You can specify a branch or branches other than just "master" in the
62-
*Primary Branches* field, if you like.
158+
At this point a test payload will be sent to your MantisBT instance.
159+
The Source Integration plugin does not actually process it, but you should
160+
check that it has been delivered successfully. A green check mark will be
161+
displayed next to the newly created Webhook, indicating success; in case of
162+
error, you will see a red warning sign instead.
63163

64-
- Click the *Update Repository* button.
164+
**NOTE:** An alternative to using Webhooks for changesets processing automation
165+
would be to schedule a cron job on your server.
65166

66-
4. If this is a private GitHub repository, you'll need to authorize Mantis
67-
to access your repository:
167+
### Initialize the repository
68168

69-
- Click the *Update Repository* button.
169+
This step will perform an initial import of the repository's changesets.
70170

71-
- Click the *Click to Authorize* button in the *GitHub Application
72-
Access Token* field. If successful, it will say "MantisBT is now
73-
authorized to access this GitHub repository."
171+
1. Go to the Manage Repository page
74172

75-
5. Click the *Import Everything* button to test connectivity and perform an
76-
initial import of the repository changesets.
173+
2. Click the **Import Everything** button
77174

78-
**Note:** This may take a long time or even fail for large repositories.
175+
**NOTE:** This may take a long time or even fail for large repositories.
176+
Failures are generally caused by timeouts on the PHP or web server side, as
177+
the maximum time allowed to execute a script is reached
178+
(see [max_execution_time](http://www.php.net/manual/en/info.configuration.php#ini.max-execution-time)).
179+
The Source Integration plugin does not handle this well; this is a
180+
[known issue](https://github.com/mantisbt-plugins/source-integration/issues/60),
181+
but unfortunately there are currently no workarounds.

0 commit comments

Comments
 (0)