From 8a88c14b13577fe8e815b4a83e42c2873a1fd364 Mon Sep 17 00:00:00 2001 From: Paulo Miguel Almeida Date: Wed, 30 Oct 2019 22:18:12 +1300 Subject: [PATCH] Add convenience method to authenticate with app installation tokens; Convert existing markdown doc to APT due to formatting features; Replace occurrences of kohsuke user to github-api org where applicable; Fix repositoryIds method on GHAppCreateTokenBuilder; Signed-off-by: PauloMigAlmeida --- pom.xml | 6 +- .../github/GHAppCreateTokenBuilder.java | 2 +- .../org/kohsuke/github/GitHubBuilder.java | 12 ++ src/site/apt/index.apt | 154 ++++++++++++++++++ src/site/site.xml | 3 +- .../java/org/kohsuke/github/GHAppTest.java | 2 +- .../kohsuke/github/GitHubConnectionTest.java | 12 +- 7 files changed, 184 insertions(+), 7 deletions(-) create mode 100644 src/site/apt/index.apt diff --git a/pom.xml b/pom.xml index e1b62de1cf..4f1be9cf7e 100644 --- a/pom.xml +++ b/pom.xml @@ -14,8 +14,8 @@ GitHub API for Java - scm:git:git@github.com/kohsuke/${project.artifactId}.git - scm:git:ssh://git@github.com/kohsuke/${project.artifactId}.git + scm:git:git@github.com/github-api/${project.artifactId}.git + scm:git:ssh://git@github.com/github-api/${project.artifactId}.git https://${project.artifactId}.kohsuke.org/ HEAD @@ -23,7 +23,7 @@ github-pages - gitsite:git@github.com/kohsuke/${project.artifactId}.git + gitsite:git@github.com/github-api/${project.artifactId}.git diff --git a/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java b/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java index cf19dd99af..807ebcf102 100644 --- a/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java +++ b/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java @@ -35,7 +35,7 @@ public class GHAppCreateTokenBuilder { * */ @Preview @Deprecated - public GHAppCreateTokenBuilder repositoryIds(List repositoryIds) { + public GHAppCreateTokenBuilder repositoryIds(List repositoryIds) { this.builder.with("repository_ids",repositoryIds); return this; } diff --git a/src/main/java/org/kohsuke/github/GitHubBuilder.java b/src/main/java/org/kohsuke/github/GitHubBuilder.java index e299e7340d..f5e640c1a9 100644 --- a/src/main/java/org/kohsuke/github/GitHubBuilder.java +++ b/src/main/java/org/kohsuke/github/GitHubBuilder.java @@ -180,6 +180,18 @@ public GitHubBuilder withOAuthToken(String oauthToken, String user) { this.user = user; return this; } + + /** + * Configures {@link GitHubBuilder} with Installation Token generated by the GitHub Application + * + * @param appInstallationToken A string containing the GitHub App installation token + * @return the configured Builder from given GitHub App installation token. + * @see GHAppInstallation#createToken(java.util.Map) + */ + public GitHubBuilder withAppInstallationToken(String appInstallationToken){ + return withOAuthToken(appInstallationToken, ""); + } + public GitHubBuilder withJwtToken(String jwtToken){ this.jwtToken = jwtToken; return this; diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 0000000000..e76dd4710b --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,154 @@ +What is this? + + This library defines an object oriented representation of the GitHub API. By "object oriented" we mean + there are classes that correspond to the domain model of GitHub (such as <<>> and <<>>), + operations that act on them as defined as methods (such as <<>>), and those object references + are used in favor of using string handle (such as <<>> instead of + <<>>) + + The library supports both github.com and GitHub Enterprise. + + Most of the GitHub APIs are covered, although there are some corners that are still not yet implemented. + +Sample Usage + ++-----+ +GitHub github = GitHub.connect(); + +GHRepository repo = github.createRepository( + "new-repository","this is my new repository", + "http://www.kohsuke.org/",true/*public*/); +repo.addCollaborators(github.getUser("abayer"),github.getUser("rtyler")); +repo.delete(); ++-----+ + +Authentication + + The library allows connecting to GitHub via several different authentication mechanisms. + +* Programmatically + + To connect via Username and Password (not recommended): + ++-----+ +GitHub github = new GitHubBuilder().withPassword("my_user", "my_passwd").build(); ++-----+ + + To connect via Personal access token: + ++-----+ +// If you don't specify the GitHub user id then the sdk will retrieve it via /user endpoint +GitHub github = new GitHubBuilder().withOAuthToken("my_personal_token").build(); + +// If the token has access to an organization, you can specify it here. +GitHub github = new GitHubBuilder().withOAuthToken("my_personal_token","user_id_OR_org_name").build(); ++-----+ + + To connect via JWT token as a GitHub App: + ++-----+ +GitHub github = new GitHubBuilder().withJwtToken("my_jwt_token").build(); ++-----+ + + To connect via GitHub App installation token on behalf of a user or organization: + ++-----+ +GitHub github = new GitHubBuilder().withAppInstallationToken("my_installation_token").build(); ++-----+ + +* Property file + + This library defines a common convention so that applications using this library will look at a consistent location. + In this convention, the library looks at <<<~/.github>>> property file. The content of the files depends on the way + you want this library to authenticate as shown below: + + + To connect via Username and Password (not recommended): + ++-----+ +login=kohsuke +password=012345678 ++-----+ + + To connect via Personal access token: + ++-----+ +oauth=4d98173f7c075527cb64878561d1fe70 ++-----+ + + To connect via Personal access token as a user or organization: + ++-----+ +login=my_org +oauth=4d98173f7c075527cb64878561d1fe70 ++-----+ + + To connect via JWT token as a GitHub App: + ++-----+ +jwt=my_jwt_token ++-----+ + + Once your <<<~/.github>>> property file is properly configured, you can obtain a <<>> instance using: + ++-----+ +// if you are using the default configuration file +GitHub github = new GitHubBuilder().fromPropertyFile().build(); + +// if you need to use a separate configuration file +GitHub github = new GitHubBuilder().fromPropertyFile("location/my_custom_github.properties").build(); ++-----+ + +* Environmental variables + + This library also allows developers to authenticate GitHub with environmental variables. + + To connect via Username and Password (not recommended): + ++-----+ +export GITHUB_LOGIN=kohsuke +export GITHUB_PASSWORD=012345678 ++-----+ + + To connect via Personal access token: + ++-----+ +export GITHUB_OAUTH=4d98173f7c075527cb64878561d1fe70 ++-----+ + + To connect via Personal access token as a user or organization: + ++-----+ +export GITHUB_LOGIN=my_org +export GITHUB_OAUTH=4d98173f7c075527cb64878561d1fe70 ++-----+ + + To connect via JWT token as a GitHub App: + ++-----+ +export GITHUB_JWT=my_jwt_token ++-----+ + + Once exported, you can obtain a <<>> instance using: + ++-----+ +GitHub github = new GitHubBuilder().fromEnvironment().build(); ++-----+ + + +Pluggable HTTP client + + This library comes with a pluggable connector to use different HTTP client implementations + through <<>>. In particular, this means you can use {{{http://square.github.io/okhttp/}OkHttp}}, + so we can make use of it's HTTP response cache. + Making a conditional request against the GitHub API and receiving a 304 response + {{{http://developer.github.com/v3/#conditional-requests}does not count against the rate limit}}. + + The following code shows an example of how to set up persistent cache on the disk: + ++-----+ +Cache cache = new Cache(cacheDirectory, 10 * 1024 * 1024); // 10MB cache +GitHub gitHub = GitHubBuilder.fromCredentials() + .withConnector(new OkHttpConnector(new OkUrlFactory(new OkHttpClient().setCache(cache)))) + .build(); ++-----+ diff --git a/src/site/site.xml b/src/site/site.xml index 01eda5ec16..3553fd23bb 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -9,12 +9,13 @@ maven-skin 1.2 + - + diff --git a/src/test/java/org/kohsuke/github/GHAppTest.java b/src/test/java/org/kohsuke/github/GHAppTest.java index baf5a12cfd..3c9bd0ff0f 100644 --- a/src/test/java/org/kohsuke/github/GHAppTest.java +++ b/src/test/java/org/kohsuke/github/GHAppTest.java @@ -103,7 +103,7 @@ public void createToken() throws IOException { permissions.put("metadata", GHPermissionType.READ); GHAppInstallationToken installationToken = installation.createToken(permissions) - .repositoryIds(Arrays.asList(111111111)) + .repositoryIds(Arrays.asList((long)111111111)) .create(); assertThat(installationToken.getToken(), is("bogus")); diff --git a/src/test/java/org/kohsuke/github/GitHubConnectionTest.java b/src/test/java/org/kohsuke/github/GitHubConnectionTest.java index 61753e94d9..5db75f6506 100644 --- a/src/test/java/org/kohsuke/github/GitHubConnectionTest.java +++ b/src/test/java/org/kohsuke/github/GitHubConnectionTest.java @@ -46,7 +46,6 @@ public void testGitHubServerWithoutServer() throws Exception { GitHub hub = GitHub.connectUsingPassword("kohsuke", "bogus"); assertEquals("https://api.github.com/test", hub.getApiURL("/test").toString()); } - @Test public void testGitHubBuilderFromEnvironment() throws IOException { @@ -86,6 +85,17 @@ public void testGitHubBuilderFromCustomEnvironment() throws IOException { assertEquals("bogusPassword", builder.password); assertEquals("bogusEndpoint", builder.endpoint); } + @Test + public void testGithubBuilderWithAppInstallationToken() throws Exception{ + GitHubBuilder builder = new GitHubBuilder().withAppInstallationToken("bogus"); + assertEquals("bogus", builder.oauthToken); + assertEquals("", builder.user); + + // test authorization header is set as in the RFC6749 + GitHub github = builder.build(); + assertEquals("token bogus",github.encodedAuthorization); + assertEquals("",github.login); + } @Test public void testGitHubRateLimit() throws Exception {