Begin implementation of Enterprise ManagementConsole API, redux (#2010)

* Initial implementation of ManagementConsole - maintenance mode * Add environment var support for management console password for integration tests * Add reactive client and unit tests * Update some xmlDoc * I think this is a better way to setup the underlying baseUri on IConneciton, to achieve managemet console access rather than requiring a specific GitHubClient that cant call normal API's Instead, the management client methods can check the base Url and if it contains /api/v3/ they can set their relative endpoint Uri to include a leading "/" which will cause the /api/v3/ to be removed. * Update EnterpriseClient.cs Fix xml comments * Update IEnterpriseClient.cs Fix xml comments * Still trying to get the xmDoc perfect, thanks app veyor :) * XmlDoc'ing my way to success * Add specific test attribute for management console tests * check chronic string empty/null * Use helper's password field in test * Tidy up maintenance mode tests by using a context/destructor to manage the initial/end state of maintenance mode * make internal and tidy up URL concatenation * move GHE endpoint fixup inside ApiUrls methods * Rework request object to be the correct structure so SimpleJsonSerializer can be used to serialize it. Remove MaintenanceDate class and just pass in the Date/string for when Still need to use UrlFormEncoding rather than json in the POST body though... * Create abstract base class for FormUrlEncoded parameters (similar to existing RequetParameters) and inherit from it in UpdateMaintenanceRequest * Fix maintenance context logic - destructor should always turn maintenance OFF regardless of initial requested state * Fix xml comment * Fix Xml comment * Those pesky xml comments! * Fine, I give up! * Fix string.Format * fix bad rebase * fix failing convention tests * restore missing whitespace * writing some docs * some edits * edit
2026-06-01 18:35:35 +00:00 · 2019-09-22 15:09:56 -03:00
parent fafbf33b78
commit 8cd0b341dd
37 changed files with 965 additions and 40 deletions
@@ -0,0 +1,73 @@
+# GitHub Enterprise Administration
+
+Octokit also ships with support for the administration APIs that GitHub
+Enterprise includes to script tasks for administrators.
+
+```c#
+var enterprise = new Uri("https://github.myenterprise.com/");
+var github = new GitHubClient("some app name", enterprise);
+github.Credentials = new Credentials("some-token-here");
+
+var stats = await github.Enterprise.AdminStats.GetStatisticsUsers();
+Console.WriteLine($"Found {stats.AdminUsers} admins, {stats.TotalUsers} total users and {stats.SuspendedUsers} suspended users");
+```
+
+Some caveats on using these APIs that you should be aware of:
+
+ - only administrators of the GitHub Enterprise instance are able to access
+   these APIs
+ - administrators creating OAuth tokens to use this endpoint must ensure the
+   `site_admin` scope is set
+ - the [Management Console API](https://developer.github.com/enterprise/2.18/v3/enterprise/management_console/)
+   also require providing the password created during setup of the GitHub
+   Enterprise installation to confirm the action
+
+You can read more about this support [on the GitHub website](https://developer.github.com/enterprise/2.18/v3/enterprise-admin/).
+
+
+## Management console
+
+To view the maintenance mode status of a GitHub Enteprise installation:
+
+```C#
+var maintenance = await github.Enterprise.ManagementConsole.GetMaintenanceMode("management-console-password");
+```
+
+To put the GitHub Enterprise installation into maintenance mode immediately:
+
+```C#
+var request = new UpdateMaintenanceRequest(new UpdateMaintenanceRequestDetails(true));
+var maintenance = await github.Enterprise.ManagementConsole.EditMaintenanceMode(
+  request,
+  "management-console-password");
+```
+
+You can also provide a human-friendly phrase based on the rules in
+[`mojombo/chronic`](https://github.com/mojombo/chronic):
+
+```C#
+var request = new UpdateMaintenanceRequest(new UpdateMaintenanceRequestDetails(true, "tomorrow at 5pm"));
+var maintenance = await github.Enterprise.ManagementConsole.EditMaintenanceMode(
+  request,
+  "management-console-password");
+```
+
+To put the GitHub Enterprise installation into maintenance mode after a period
+of time:
+
+```C#
+var scheduledTime = DateTimeOffset.Now.AddMinutes(10);
+var request = new UpdateMaintenanceRequest(new UpdateMaintenanceRequestDetails(true, scheduledTime));
+var maintenance = await github.Enterprise.ManagementConsole.EditMaintenanceMode(
+  request,
+  "management-console-password");
+```
+
+To disable maintenance mode, simple pass in `false` or leave the `request`
+constructor empty:
+
+```c#
+var maintenance = await github.Enterprise.ManagementConsole.EditMaintenanceMode(
+  new UpdateMaintenanceRequest(), // off by default if nothing specified
+  "management-console-password");
+```