Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-33228

GitHub server configuration undocumented / duplicated

      If I install this plugin, and attempt to use it with a GitHub Enterprise server (via New Item > Multibranch pipeline > Branch Sources > GitHub), there isn't any documentation.

      I discovered that there is a "API endpoint" dropdown, but it just says "GitHub" and has no documentation.

      If I go to Manage Jenkins > Manage System, I see two different places to configure GitHub servers — one comes from the GitHub plugin, which is a dependency. This is directly followed by a duplicate, but less-detailed configuration UI, provided by this plugin.

      Ideally, there should be one single, documented place to enter the required information.

          [JENKINS-33228] GitHub server configuration undocumented / duplicated

          Kirill Merkushev added a comment - - edited

          Think it should reuse github-plugin's credentials storage and not use own. I can help on how to do so - it requires only few lines of code

          Kirill Merkushev added a comment - - edited Think it should reuse github-plugin's credentials storage and not use own. I can help on how to do so - it requires only few lines of code

          github-plugin provides API for hooks registration and GH connection with credentials UI. It kept as generic functionality plugin (plus very annoying push->git-poll trigger that can't be removed). User configures GH connection and then plugins reusing it. As i see branch-source fully rewrote this functionality with allowing totally bad things like using user+password logins and anonymous connections. Excluding `github-plugin` for github plugins unfortunately would mean that CloudBees doesn't want to use community produced code and APIs.

          Kanstantsin Shautsou added a comment - github-plugin provides API for hooks registration and GH connection with credentials UI. It kept as generic functionality plugin (plus very annoying push->git-poll trigger that can't be removed). User configures GH connection and then plugins reusing it. As i see branch-source fully rewrote this functionality with allowing totally bad things like using user+password logins and anonymous connections. Excluding `github-plugin` for github plugins unfortunately would mean that CloudBees doesn't want to use community produced code and APIs.

          Global configuration provided for this plugin to handle GitHub Entreprise instances, IMO, it is enough.

          Yeah... if the existing UI was good enough, then I wouldn't have filed this issue, and cleclerc wouldn't have submitted PR #25!

          Firstly, someone seeing "API endpoint" as a configuration option won't magically know that this is supposed to be a URL pointing to the base path of the API on the GitHub Enteprise server. Even if they do enter a URL, they will probably see "This does not look like a GitHub Enterprise API URL".

          What should they do when they see this? What should a GH Enterprise API URL look like? Again, there is zero inline documentation.

          There are even three different code paths which show this same message at the moment — one of which is wrong, since if the GH Enterprise instance has anonymous access disabled, you'll get an IOException: "WARNING: Server returned HTTP response code: 401 for URL: https://github.example.de/api/v3/"


          Anyway, aside from the fact that every config option should be clearly named and clearly documented, it misses the main point — the needless duplication.

          As a user, I don't really care which dependency this plugin uses, so long as the UI is consistent. If relying on the github-plugin makes it more consistent, then great. If this plugin and the github-plugin both end up relying on some new github-library-ui plugin, also great. But right now, the duplication of UI here makes no sense.

          Christopher Orr added a comment - Global configuration provided for this plugin to handle GitHub Entreprise instances, IMO, it is enough. Yeah... if the existing UI was good enough, then I wouldn't have filed this issue, and cleclerc wouldn't have submitted PR #25 ! Firstly, someone seeing "API endpoint" as a configuration option won't magically know that this is supposed to be a URL pointing to the base path of the API on the GitHub Enteprise server. Even if they do enter a URL, they will probably see "This does not look like a GitHub Enterprise API URL". What should they do when they see this? What should a GH Enterprise API URL look like? Again, there is zero inline documentation. There are even three different code paths which show this same message at the moment — one of which is wrong, since if the GH Enterprise instance has anonymous access disabled, you'll get an IOException: "WARNING: Server returned HTTP response code: 401 for URL: https://github.example.de/api/v3/ " Anyway, aside from the fact that every config option should be clearly named and clearly documented, it misses the main point — the needless duplication. As a user, I don't really care which dependency this plugin uses, so long as the UI is consistent. If relying on the github-plugin makes it more consistent, then great. If this plugin and the github-plugin both end up relying on some new github-library-ui plugin, also great. But right now, the duplication of UI here makes no sense.

          orrc Thanks for your feedback.

          Manuel Recena Soto added a comment - orrc Thanks for your feedback.

          Jesse Glick added a comment -

          Yes, this should be fixed. My general preference would be to move APIs and global configuration options into a separate plugin that could be reused by various feature plugins, but just properly using the existing APIs in the github plugin is the first step.

          Jesse Glick added a comment - Yes, this should be fixed. My general preference would be to move APIs and global configuration options into a separate plugin that could be reused by various feature plugins, but just properly using the existing APIs in the github plugin is the first step.

          I've updated the Issue Links section with information that it will help to improve a bit this issue. I'm working on JENKINS-33318.

          Manuel Recena Soto added a comment - I've updated the Issue Links section with information that it will help to improve a bit this issue. I'm working on JENKINS-33318 .

          Patrick Wolf added a comment -

          I agree with jglick. We should use the existing APIs here to simplify the user experience. Even if we remove the dependency on the github-plugin there are many installations that already include this plugin. That doesn't really solve the problem.

          Patrick Wolf added a comment - I agree with jglick . We should use the existing APIs here to simplify the user experience. Even if we remove the dependency on the github-plugin there are many installations that already include this plugin. That doesn't really solve the problem.

          This "GitHub Enterprise Server" configuration appears to be necessary only because the API endpoint configuration is a drop-down instead of textbox.

          I think an easy fix is just to turn it into the textbox and remove the global configuration. A textbox can have auto-completion configured to pick up API endpoint values from github plugin and other organization folders.

          For GitHub plugin configuration to become reusable for other plugins, it needs some work, too...

          Kohsuke Kawaguchi added a comment - This "GitHub Enterprise Server" configuration appears to be necessary only because the API endpoint configuration is a drop-down instead of textbox. I think an easy fix is just to turn it into the textbox and remove the global configuration. A textbox can have auto-completion configured to pick up API endpoint values from github plugin and other organization folders. For GitHub plugin configuration to become reusable for other plugins, it needs some work, too...

          Code changed in jenkins
          User: Kohsuke Kawaguchi
          Path:
          src/main/java/org/jenkinsci/plugins/github/config/GitHubPluginConfig.java
          http://jenkins-ci.org/commit/github-plugin/dc3319946ca0dfbe2609ba359b72452a18bb31ed
          Log:
          Nobody cares what plugin is being configured!

          ... especially so if this plugin is meant to be a common configuration point for all GitHub related plugins, ala JENKINS-33228.

          SCM/JIRA link daemon added a comment - Code changed in jenkins User: Kohsuke Kawaguchi Path: src/main/java/org/jenkinsci/plugins/github/config/GitHubPluginConfig.java http://jenkins-ci.org/commit/github-plugin/dc3319946ca0dfbe2609ba359b72452a18bb31ed Log: Nobody cares what plugin is being configured! ... especially so if this plugin is meant to be a common configuration point for all GitHub related plugins, ala JENKINS-33228 .

          Code changed in jenkins
          User: Merkushev Kirill
          Path:
          src/main/java/org/jenkinsci/plugins/github/config/GitHubPluginConfig.java
          src/main/java/org/jenkinsci/plugins/github/config/GitHubServerConfig.java
          src/main/java/org/jenkinsci/plugins/github/migration/Migrator.java
          src/main/resources/org/jenkinsci/plugins/github/config/GitHubPluginConfig/config.groovy
          src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/config.groovy
          src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-apiUrl.html
          src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-clientCacheSize.html
          src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-customApiUrl.html
          src/test/java/org/jenkinsci/plugins/github/config/GitHubServerConfigTest.java
          src/test/java/org/jenkinsci/plugins/github/internal/GitHubClientCacheCleanupTest.java
          src/test/java/org/jenkinsci/plugins/github/internal/GitHubClientCacheOpsTest.java
          src/test/java/org/jenkinsci/plugins/github/test/GHMockRule.java
          http://jenkins-ci.org/commit/github-plugin/44a87816b187bd21a32e7942f3830ca3f6fbfa45
          Log:
          Merge pull request #112 from jenkinsci/config-improvements

          JENKINS-33228 Misc global config page improvements

          Compare: https://github.com/jenkinsci/github-plugin/compare/20c159e05809...44a87816b187

          SCM/JIRA link daemon added a comment - Code changed in jenkins User: Merkushev Kirill Path: src/main/java/org/jenkinsci/plugins/github/config/GitHubPluginConfig.java src/main/java/org/jenkinsci/plugins/github/config/GitHubServerConfig.java src/main/java/org/jenkinsci/plugins/github/migration/Migrator.java src/main/resources/org/jenkinsci/plugins/github/config/GitHubPluginConfig/config.groovy src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/config.groovy src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-apiUrl.html src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-clientCacheSize.html src/main/resources/org/jenkinsci/plugins/github/config/GitHubServerConfig/help-customApiUrl.html src/test/java/org/jenkinsci/plugins/github/config/GitHubServerConfigTest.java src/test/java/org/jenkinsci/plugins/github/internal/GitHubClientCacheCleanupTest.java src/test/java/org/jenkinsci/plugins/github/internal/GitHubClientCacheOpsTest.java src/test/java/org/jenkinsci/plugins/github/test/GHMockRule.java http://jenkins-ci.org/commit/github-plugin/44a87816b187bd21a32e7942f3830ca3f6fbfa45 Log: Merge pull request #112 from jenkinsci/config-improvements JENKINS-33228 Misc global config page improvements Compare: https://github.com/jenkinsci/github-plugin/compare/20c159e05809...44a87816b187

            cloudbees CloudBees Inc.
            orrc Christopher Orr
            Votes:
            1 Vote for this issue
            Watchers:
            10 Start watching this issue

              Created:
              Updated: