diff --git a/README.md b/README.md index e374770..d2e6441 100644 --- a/README.md +++ b/README.md @@ -77,37 +77,37 @@ NOTE: an API Key must be set up to import changesets via shell. To generate a random key, run - + openssl rand -hex 12 7. Go to "Repositories" and enter your repository name, select the repository type, and click "Create Repository" to begin adding your first repository. -8. Configuring the repository is plugin-specific, so see the specific - configuration documentation: - - * [docs/CONFIGURING.SourceGithub.md](docs/CONFIGURING.SourceGithub.md) +8. Configure the repository, following the specific documentation for the + relevant plugin extension: + + * [SourceGithub](docs/CONFIGURING.SourceGithub.md) 9. Once configured, click the "Return to Repository" link and click either - the "Import Everything" or "Import Newest Data" button to perform initial + the "Import Everything" or "Import Newest Data" button to perform initial import of repository changesets and verify configuration. 10. Once satisfied that your repository is configured & working correctly, - you can automate the import of new changesets by configuring a cron - job on the web server where your Mantis installation resides, as follows: + you can automate the import of new changesets by configuring a cron + job on the web server where your Mantis installation resides, as follows: - a. import via curl (could run into timeouts on large repositories, - or block your webserver) + a. import via curl (could run into timeouts on large repositories, + or block your webserver) - curl "http://host.domain.tld/mantisbt/plugin.php?page=Source/import&id=all" + curl "http://host.domain.tld/mantisbt/plugin.php?page=Source/import&id=all" - b. import via shell + b. import via shell - php-cgi -f plugin.php page=Source/import id=all api_key= + php-cgi -f plugin.php page=Source/import id=all api_key= - This will import new changesets for all configured repositories. + This will import new changesets for all configured repositories. 11. Add additional repositories as needed. diff --git a/docs/CONFIGURING.SourceGithub.md b/docs/CONFIGURING.SourceGithub.md index 63c1416..536580f 100644 --- a/docs/CONFIGURING.SourceGithub.md +++ b/docs/CONFIGURING.SourceGithub.md @@ -1,89 +1,88 @@ - # SourceGithub Configuration ## Description -The **SourceGithub** plugin adds support for Git repositories hosted on -[GitHub](http://github.com/), both public & private (presonal & organization) -repositories. +The **SourceGithub** extension plugin adds support for Git repositories +hosted on [GitHub](http://github.com/), both public & private as well as +personal & organization repositories. -**NOTE:** As of this writing the **SourceGithub** plugin requires either Mantis -1.2.16 (not yet released) or Mantis 1.2.15 with the -[mantisbt/mantisbt@8df9d5f](http://github.com/mantisbt/mantisbt/commit/8df9d5fa221bb85f9f8c1ca6b698d75b740d6449) -patch applied. This is due to a new requirement in GitHub API v3 ([User Agent -header is mandatory for all API -requests](http://developer.github.com/changes/2013-04-24-user-agent-required/)) -enforced as of 2013-04-24. -## +## Requirements -1. Ensure both the **Source** and **SourceGithub** plugins are installed. See -the [README](../README.md#installation) for overall instructions. +The **SourceGithub** plugin requires Mantis 1.2.16. See the +[README](../README.md#requirements) for further information. -2. Click the "Repositories" link in the navigation bar. +Ensure both the **Source** and **SourceGithub** plugins are installed. +See the [README](../README.md#installation) for overall instructions. -3. In the "Create Repository" section: - + +## Configuration + +1. Click the "Repositories" link in the navigation bar. + +2. In the "Create Repository" section: + a. Enter the repository name in the "Name" text field. - + b. Select "GitHub" from the "Type" pop-up menu. - + c. Click the "Create Repository" button. -4. This will take you to the "Update Repository" page where you'll need to fill +3. This will take you to the "Update Repository" page where you'll need to fill in all the details for the repository: - - a. The "Name" field should be pre-populated with the name you entered in + + a. The "Name" field should be pre-populated with the name you entered in Step 3a. - - b. Paste in the GitHub repositories URL in the "URL" field (e.g. + + b. Paste in the GitHub repository's URL in the "URL" field (e.g. `https://github.com/mantisbt-plugins/source-integration`). - - c. Enter the GitHub username of the repository's owner in the "GitHub Username" + + c. Enter the GitHub username of the repository's owner in the "GitHub Username" field (e.g. "mantisbt-plugins"). - - d. Enter the GitHub repository's name in the "GitHub Repository Name" field + + d. Enter the GitHub repository's name in the "GitHub Repository Name" field (e.g. "source-integration"). - - e. If it's a public GitHub repository, you can skip the "GitHub Application - Client ID" & "GitHub Application Secret" fields. If it's a private + + e. If it's a public GitHub repository, you can skip the "GitHub Application + Client ID" & "GitHub Application Secret" fields. If it's a private repository, you'll need to configure a GitHub Developer Application: - - I. Visit https://github.com/settings/developers and click the "Register + + 1. Visit https://github.com/settings/developers and click the "Register new application" button. - - II. Enter "MantisBT Source Integration" in the "Application name" field. - - III. Enter the URL for your Mantis installation in the "Homepage URL" + + 2. Enter "MantisBT Source Integration" in the "Application name" field. + + 3. Enter the URL for your Mantis installation in the "Homepage URL" field. - - IV. Enter the URL for your Mantis Source/oauth page (the URL with + + 4. Enter the URL for your Mantis Source/oauth page (the URL with "/plugin.php?page=Source/oauth" appended to it; e.g. "http://mantisbt.org/bugs/plugin.php?page=Source/oauth"). - - V. Click the "Register application" button. - - VI. Switch back to your Mantis GitHub Repository configuration. - - VII. Enter your GitHub Developer Application's Client ID in the "GitHub + + 5. Click the "Register application" button. + + 6. Switch back to your Mantis GitHub Repository configuration. + + 7. Enter your GitHub Developer Application's Client ID in the "GitHub Application Client ID" field. - - VIII. Enter your GitHub Developer Application's Secret in the "GitHub + + 8. Enter your GitHub Developer Application's Secret in the "GitHub Application Access Secret" field. - - f. You can specify a branch or branches other than just "master" in the + + f. You can specify a branch or branches other than just "master" in the "Primary Branches" field, if you like. - - g. Click the "Update Repository" button. - -5. If this is a private GitHub repository, you'll need to authorize Mantis + + g. Click the "Update Repository" button. + +4. If this is a private GitHub repository, you'll need to authorize Mantis to access your repository, so do the following: - - a. Click the "Update Repository" button. - - b. Click the "Click to Authorize" button in the "GitHub Application + + a. Click the "Update Repository" button. + + b. Click the "Click to Authorize" button in the "GitHub Application Access Token" field. If successful, it will say "MantisBT is now authorized to access this GitHub repository." - -6. Click the "Import Everything" button to test connectivity and perform an - initial import of the repository changesets. **Note:** This may take a - long time or fail for large repositories. + +5. Click the "Import Everything" button to test connectivity and perform an + initial import of the repository changesets. + + **Note:** This may take a long time or even fail for large repositories.