[maven-release-plugin] prepare release github-api-1.87

Add basic support for tag objects

.gitignore

@@ -3,3 +3,7 @@ target
 *.iml
 *.ipr
 *.iws
+.classpath
+.project
+.settings/
+.DS_Store

pom.xml

@@ -3,11 +3,11 @@
   <parent>
     <groupId>org.kohsuke</groupId>
     <artifactId>pom</artifactId>
-    <version>14</version>
+    <version>17</version>
   </parent>
 
   <artifactId>github-api</artifactId>
-  <version>1.81</version>
+  <version>1.87</version>
   <name>GitHub API for Java</name>
   <url>http://github-api.kohsuke.org/</url>
   <description>GitHub API for Java</description>
@@ -16,7 +16,7 @@
     <connection>scm:git:git@github.com/kohsuke/${project.artifactId}.git</connection>
     <developerConnection>scm:git:ssh://git@github.com/kohsuke/${project.artifactId}.git</developerConnection>
     <url>http://${project.artifactId}.kohsuke.org/</url>
-    <tag>github-api-1.81</tag>
+    <tag>github-api-1.87</tag>
   </scm>
 
   <distributionManagement>
@@ -34,6 +34,12 @@
 
   <build>
     <plugins>
+      <plugin>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <configuration>
+          <rerunFailingTestsCount>2</rerunFailingTestsCount>
+        </configuration>
+      </plugin>
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>animal-sniffer-maven-plugin</artifactId>

src/main/java/org/kohsuke/github/BranchProtection.java

@@ -1,21 +0,0 @@
-package org.kohsuke.github;
-
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
-
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * @author Kohsuke Kawaguchi
- * @see GHBranch#disableProtection()
- */
-@SuppressFBWarnings(value = {"UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD"}, justification = "JSON API")
-class BranchProtection {
-    boolean enabled;
-    RequiredStatusChecks requiredStatusChecks;
-
-    static class RequiredStatusChecks {
-        EnforcementLevel enforcement_level;
-        List<String> contexts = new ArrayList<String>();
-    }
-}

src/main/java/org/kohsuke/github/EnforcementLevel.java

@@ -3,8 +3,11 @@ package org.kohsuke.github;
 import java.util.Locale;
 
 /**
+ * This was added during preview API period but it has changed since then.
+ *
  * @author Kohsuke Kawaguchi
  */
+@Deprecated
 public enum EnforcementLevel {
     OFF, NON_ADMINS, EVERYONE;
 

src/main/java/org/kohsuke/github/GHBlob.java

@@ -0,0 +1,64 @@
+package org.kohsuke.github;
+
+import org.apache.commons.codec.binary.Base64InputStream;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.io.UnsupportedEncodingException;
+import java.net.URL;
+
+/**
+ * @author Kanstantsin Shautsou
+ * @author Kohsuke Kawaguchi
+ * @see GHTreeEntry#asBlob()
+ * @see GHRepository#getBlob(String)
+ * @see <a href="https://developer.github.com/v3/git/blobs/#get-a-blob">Get a blob</a>
+ */
+public class GHBlob {
+    private String content, encoding, url, sha;
+    private long size;
+
+    /**
+     * API URL of this blob.
+     */
+    public URL getUrl() {
+        return GitHub.parseURL(url);
+    }
+
+    public String getSha() {
+        return sha;
+    }
+
+    /**
+     * Number of bytes in this blob.
+     */
+    public long getSize() {
+        return size;
+    }
+
+    public String getEncoding() {
+        return encoding;
+    }
+
+    /**
+     * Encoded content. You probably want {@link #read()}
+     */
+    public String getContent() {
+        return content;
+    }
+
+    /**
+     * Retrieves the actual bytes of the blob.
+     */
+    public InputStream read() {
+        if (encoding.equals("base64")) {
+            try {
+                return new Base64InputStream(new ByteArrayInputStream(content.getBytes("US-ASCII")), false);
+            } catch (UnsupportedEncodingException e) {
+                throw new AssertionError(e);    // US-ASCII is mandatory
+            }
+        }
+
+        throw new UnsupportedOperationException("Unrecognized encoding: "+encoding);
+    }
+}

src/main/java/org/kohsuke/github/GHBranch.java

@@ -1,20 +1,21 @@
 package org.kohsuke.github;
 
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
-import org.kohsuke.github.BranchProtection.RequiredStatusChecks;
-
-import java.io.IOException;
-import java.util.Arrays;
-import java.util.Collection;
-
 import static org.kohsuke.github.Previews.LOKI;
 
+import java.io.IOException;
+import java.net.URL;
+import java.util.Collection;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
 /**
  * A branch in a repository.
- * 
+ *
  * @author Yusuke Kokubo
  */
-@SuppressFBWarnings(value = {"UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", 
+@SuppressFBWarnings(value = {"UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD",
     "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD"}, justification = "JSON API")
 public class GHBranch {
     private GitHub root;
@@ -22,10 +23,14 @@ public class GHBranch {
 
     private String name;
     private Commit commit;
+    @JsonProperty("protected")
+    private boolean protection;
+    private String protection_url;
+
 
     public static class Commit {
         String sha;
-        
+
         @SuppressFBWarnings(value = "UUF_UNUSED_FIELD", justification = "We don't provide it in API now")
         String url;
     }
@@ -45,6 +50,27 @@ public class GHBranch {
         return name;
     }
 
+    /**
+     * Returns true if the push to this branch is restricted via branch protection.
+     */
+    @Preview @Deprecated
+    public boolean isProtected() {
+        return protection;
+    }
+
+    /**
+     * Returns API URL that deals with the protection of this branch.
+     */
+    @Preview @Deprecated
+    public URL getProtectionUrl() {
+        return GitHub.parseURL(protection_url);
+    }
+
+    @Preview @Deprecated
+    public GHBranchProtection getProtection() throws IOException {
+        return root.retrieve().withPreview(LOKI).to(protection_url, GHBranchProtection.class);
+    }
+
     /**
      * The commit that this branch currently points to.
      */
@@ -57,9 +83,7 @@ public class GHBranch {
      */
     @Preview @Deprecated
     public void disableProtection() throws IOException {
-        BranchProtection bp = new BranchProtection();
-        bp.enabled = false;
-        setProtection(bp);
+        new Requester(root).method("DELETE").withPreview(LOKI).to(protection_url);
     }
 
     /**
@@ -68,28 +92,31 @@ public class GHBranch {
      * @see GHCommitStatus#getContext()
      */
     @Preview @Deprecated
+    public GHBranchProtectionBuilder enableProtection() {
+        return new GHBranchProtectionBuilder(this);
+    }
+
+    // backward compatibility with previous signature
+    @Deprecated
     public void enableProtection(EnforcementLevel level, Collection<String> contexts) throws IOException {
-        BranchProtection bp = new BranchProtection();
-        bp.enabled = true;
-        bp.requiredStatusChecks = new RequiredStatusChecks();
-        bp.requiredStatusChecks.enforcement_level = level;
-        bp.requiredStatusChecks.contexts.addAll(contexts);
-        setProtection(bp);
-    }
-
-    @Preview @Deprecated
-    public void enableProtection(EnforcementLevel level, String... contexts) throws IOException {
-        enableProtection(level, Arrays.asList(contexts));
-    }
-
-    private void setProtection(BranchProtection bp) throws IOException {
-        new Requester(root).method("PATCH").withPreview(LOKI)._with("protection",bp).to(getApiRoute());
+        switch (level) {
+        case OFF:
+            disableProtection();
+            break;
+        case NON_ADMINS:
+        case EVERYONE:
+            enableProtection()
+                .addRequiredChecks(contexts)
+                .includeAdmins(level==EnforcementLevel.EVERYONE)
+                .enable();
+            break;
+        }
     }
 
     String getApiRoute() {
         return owner.getApiTailUrl("/branches/"+name);
     }
-    
+
     @Override
     public String toString() {
         final String url = owner != null ? owner.getUrl().toString() : "unknown";

src/main/java/org/kohsuke/github/GHBranchProtection.java

@@ -0,0 +1,152 @@
+package org.kohsuke.github;
+
+import java.util.Collection;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+@SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD",
+		"URF_UNREAD_FIELD" }, justification = "JSON API")
+public class GHBranchProtection {
+	@JsonProperty("enforce_admins")
+	private EnforceAdmins enforceAdmins;
+
+	@JsonProperty("required_pull_request_reviews")
+	private RequiredReviews requiredReviews;
+
+	@JsonProperty("required_status_checks")
+	private RequiredStatusChecks requiredStatusChecks;
+
+	@JsonProperty
+	private Restrictions restrictions;
+
+	@JsonProperty
+	private String url;
+	
+	public EnforceAdmins getEnforceAdmins() {
+        return enforceAdmins;
+    }
+
+    public RequiredReviews getRequiredReviews() {
+        return requiredReviews;
+    }
+
+    public RequiredStatusChecks getRequiredStatusChecks() {
+        return requiredStatusChecks;
+    }
+
+    public Restrictions getRestrictions() {
+        return restrictions;
+    }
+
+    public String getUrl() {
+        return url;
+    }
+
+    public static class EnforceAdmins {
+		@JsonProperty
+		private boolean enabled;
+
+		@JsonProperty
+		private String url;
+
+        public String getUrl() {
+            return url;
+        }
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+	}
+
+	public static class RequiredReviews {
+		@JsonProperty("dismissal_restrictions")
+		private Restrictions dismissalRestriction; 
+
+		@JsonProperty("dismiss_stale_reviews")
+		private boolean dismissStaleReviews;
+
+		@JsonProperty("require_code_owner_reviews")
+		private boolean requireCodeOwnerReviews;
+
+		@JsonProperty
+		private String url;
+
+        public Restrictions getDismissalRestrictions() {
+            return dismissalRestriction;
+        }
+
+        public String getUrl() {
+            return url;
+        }
+
+        public boolean isDismissStaleReviews() {
+            return dismissStaleReviews;
+        }
+
+        public boolean isRequireCodeOwnerReviews() {
+            return requireCodeOwnerReviews;
+        }
+	}
+
+	public static class RequiredStatusChecks {
+		@JsonProperty
+		private Collection<String> contexts;
+
+		@JsonProperty
+		private boolean strict;
+
+		@JsonProperty
+		private String url;
+
+        public Collection<String> getContexts() {
+            return contexts;
+        }
+
+        public String getUrl() {
+            return url;
+        }
+
+        public boolean isRequiresBranchUpToDate() {
+            return strict;
+        }
+	}
+
+	public static class Restrictions {
+		@JsonProperty
+		private Collection<GHTeam> teams;
+
+		@JsonProperty("teams_url")
+		private String teamsUrl;
+
+		@JsonProperty
+		private String url;
+
+		@JsonProperty
+		private Collection<GHUser> users;
+
+		@JsonProperty("users_url")
+		private String usersUrl;
+
+        public Collection<GHTeam> getTeams() {
+            return teams;
+        }
+
+        public String getTeamsUrl() {
+            return teamsUrl;
+        }
+
+        public String getUrl() {
+            return url;
+        }
+
+        public Collection<GHUser> getUsers() {
+            return users;
+        }
+
+        public String getUsersUrl() {
+            return usersUrl;
+        }
+	}
+}

src/main/java/org/kohsuke/github/GHBranchProtectionBuilder.java

@@ -0,0 +1,203 @@
+package org.kohsuke.github;
+
+import static org.kohsuke.github.Previews.LOKI;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+/**
+ * Builder to configure the branch protection settings.
+ *
+ * @see GHBranch#enableProtection()
+ */
+@SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD",
+        "URF_UNREAD_FIELD" }, justification = "JSON API")
+public class GHBranchProtectionBuilder {
+    private final GHBranch branch;
+
+    private boolean enforceAdmins;
+    private Map<String, Object> prReviews;
+    private Restrictions restrictions;
+    private StatusChecks statusChecks;
+
+    GHBranchProtectionBuilder(GHBranch branch) {
+        this.branch = branch;
+    }
+
+    public GHBranchProtectionBuilder addRequiredChecks(Collection<String> checks) {
+        getStatusChecks().contexts.addAll(checks);
+        return this;
+    }
+    
+    public GHBranchProtectionBuilder addRequiredChecks(String... checks) {
+        addRequiredChecks(Arrays.asList(checks));
+        return this;
+    }
+
+    public GHBranchProtectionBuilder dismissStaleReviews() {
+        getPrReviews().put("dismiss_stale_reviews", true);
+        return this;
+    }
+
+    public GHBranchProtection enable() throws IOException {
+        return requester().method("PUT")
+                .withNullable("required_status_checks", statusChecks)
+                .withNullable("required_pull_request_reviews", prReviews)
+                .withNullable("restrictions", restrictions)
+                .withNullable("enforce_admins", enforceAdmins)
+                .to(branch.getProtectionUrl().toString(), GHBranchProtection.class);
+    }
+
+    public GHBranchProtectionBuilder includeAdmins() {
+        return includeAdmins(true);
+    }
+
+    public GHBranchProtectionBuilder includeAdmins(boolean v) {
+        enforceAdmins = v;
+        return this;
+    }
+
+    public GHBranchProtectionBuilder requireBranchIsUpToDate() {
+        return requireBranchIsUpToDate(true);
+    }
+
+    public GHBranchProtectionBuilder requireBranchIsUpToDate(boolean v) {
+        getStatusChecks().strict = v;
+        return this;
+    }
+
+    public GHBranchProtectionBuilder requireCodeOwnReviews() {
+        return requireCodeOwnReviews(true);
+    }
+
+    public GHBranchProtectionBuilder requireCodeOwnReviews(boolean v) {
+        getPrReviews().put("require_code_owner_reviews", v);
+        return this;
+    }
+
+    public GHBranchProtectionBuilder requireReviews() {
+        getPrReviews();
+        return this;
+    }
+
+    public GHBranchProtectionBuilder restrictPushAccess() {
+        getRestrictions();
+        return this;
+    }
+
+    public GHBranchProtectionBuilder teamPushAccess(Collection<GHTeam> teams) {
+        for (GHTeam team : teams) {
+            teamPushAccess(team);
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder teamPushAccess(GHTeam... teams) {
+        for (GHTeam team : teams) {
+            getRestrictions().teams.add(team.getSlug());
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder teamReviewDismissals(Collection<GHTeam> teams) {
+        for (GHTeam team : teams) {
+            teamReviewDismissals(team);
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder teamReviewDismissals(GHTeam... teams) {
+        for (GHTeam team : teams) {
+            addReviewRestriction(team.getSlug(), true);
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder userPushAccess(Collection<GHUser> users) {
+        for (GHUser user : users) {
+            userPushAccess(user);
+        }
+        return this;
+    }
+    
+    public GHBranchProtectionBuilder userPushAccess(GHUser... users) {
+        for (GHUser user : users) {
+            getRestrictions().users.add(user.getLogin());
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder userReviewDismissals(Collection<GHUser> users) {
+        for (GHUser team : users) {
+            userReviewDismissals(team);
+        }
+        return this;
+    }
+
+    public GHBranchProtectionBuilder userReviewDismissals(GHUser... users) {
+        for (GHUser user : users) {
+            addReviewRestriction(user.getLogin(), false);
+        }
+        return this;
+    }
+
+    private void addReviewRestriction(String restriction, boolean isTeam) {
+        getPrReviews();
+        
+        if (!prReviews.containsKey("dismissal_restrictions")) {
+            prReviews.put("dismissal_restrictions", new Restrictions());
+        }
+        
+        Restrictions restrictions = (Restrictions) prReviews.get("dismissal_restrictions");
+        
+        if (isTeam) {
+            restrictions.teams.add(restriction);
+        } else {
+            restrictions.users.add(restriction);
+        }
+    }
+
+    private Map<String, Object> getPrReviews() {
+        if (prReviews == null) {
+            prReviews = new HashMap<String, Object>();
+        }
+        return prReviews;
+    }
+
+    private Restrictions getRestrictions() {
+        if (restrictions == null) {
+            restrictions = new Restrictions();
+        }
+        return restrictions;
+    }
+
+    private StatusChecks getStatusChecks() {
+        if (statusChecks == null) {
+            statusChecks = new StatusChecks();
+        }
+        return statusChecks;
+    }
+
+    private Requester requester() {
+        return new Requester(branch.getRoot()).withPreview(LOKI);
+    }
+
+    private static class Restrictions {
+        private Set<String> teams = new HashSet<String>();
+        private Set<String> users = new HashSet<String>();
+    }
+
+    private static class StatusChecks {
+        final List<String> contexts = new ArrayList<String>();
+        boolean strict;
+    }
+}

src/main/java/org/kohsuke/github/GHCommit.java

@@ -37,6 +37,12 @@ public class GHCommit {
         
         private int comment_count;
 
+        static class Tree {
+            String sha;
+        }
+
+        private Tree tree;
+
         @WithBridgeMethods(value = GHAuthor.class, castRequired = true)
         public GitUser getAuthor() {
             return author;
@@ -224,6 +230,13 @@ public class GHCommit {
         return stats.deletions;
     }
 
+    /**
+     * Use this method to walk the tree
+     */
+    public GHTree getTree() throws IOException {
+        return owner.getTree(getCommitShortInfo().tree.sha);
+    }
+
     /**
      *  URL of this commit like "https://github.com/kohsuke/sandbox-ant/commit/8ae38db0ea5837313ab5f39d43a6f73de3bd9000"
      */

src/main/java/org/kohsuke/github/GHCommitSearchBuilder.java

@@ -0,0 +1,137 @@
+package org.kohsuke.github;
+
+import java.io.IOException;
+
+import org.apache.commons.lang.StringUtils;
+
+/**
+ * Search commits.
+ *
+ * @author Marc de Verdelhan
+ * @see GitHub#searchCommits()
+ */
+@Preview @Deprecated
+public class GHCommitSearchBuilder extends GHSearchBuilder<GHCommit> {
+    /*package*/ GHCommitSearchBuilder(GitHub root) {
+        super(root,CommitSearchResult.class);
+        req.withPreview(Previews.CLOAK);
+    }
+
+    /**
+     * Search terms.
+     */
+    public GHCommitSearchBuilder q(String term) {
+        super.q(term);
+        return this;
+    }
+
+    public GHCommitSearchBuilder author(String v) {
+        return q("author:"+v);
+    }
+
+    public GHCommitSearchBuilder committer(String v) {
+        return q("committer:"+v);
+    }
+
+    public GHCommitSearchBuilder authorName(String v) {
+        return q("author-name:"+v);
+    }
+
+    public GHCommitSearchBuilder committerName(String v) {
+        return q("committer-name:"+v);
+    }
+
+    public GHCommitSearchBuilder authorEmail(String v) {
+        return q("author-email:"+v);
+    }
+
+    public GHCommitSearchBuilder committerEmail(String v) {
+        return q("committer-email:"+v);
+    }
+
+    public GHCommitSearchBuilder authorDate(String v) {
+        return q("author-date:"+v);
+    }
+
+    public GHCommitSearchBuilder committerDate(String v) {
+        return q("committer-date:"+v);
+    }
+
+    public GHCommitSearchBuilder merge(boolean merge) {
+        return q("merge:"+Boolean.valueOf(merge).toString().toLowerCase());
+    }
+
+    public GHCommitSearchBuilder hash(String v) {
+        return q("hash:"+v);
+    }
+
+    public GHCommitSearchBuilder parent(String v) {
+        return q("parent:"+v);
+    }
+
+    public GHCommitSearchBuilder tree(String v) {
+        return q("tree:"+v);
+    }
+
+    public GHCommitSearchBuilder is(String v) {
+        return q("is:"+v);
+    }
+
+    public GHCommitSearchBuilder user(String v) {
+        return q("user:"+v);
+    }
+
+    public GHCommitSearchBuilder org(String v) {
+        return q("org:"+v);
+    }
+
+    public GHCommitSearchBuilder repo(String v) {
+        return q("repo:"+v);
+    }
+
+    public GHCommitSearchBuilder order(GHDirection v) {
+        req.with("order",v);
+        return this;
+    }
+
+    public GHCommitSearchBuilder sort(Sort sort) {
+        req.with("sort",sort);
+        return this;
+    }
+
+    public enum Sort { AUTHOR_DATE, COMMITTER_DATE }
+
+    private static class CommitSearchResult extends SearchResult<GHCommit> {
+        private GHCommit[] items;
+
+        @Override
+        /*package*/ GHCommit[] getItems(GitHub root) {
+            for (GHCommit commit : items) {
+                String repoName = getRepoName(commit.url);
+                try {
+                    GHRepository repo = root.getRepository(repoName);
+                    commit.wrapUp(repo);
+                } catch (IOException ioe) {}
+            }
+            return items;
+        }
+    }
+    
+    /**
+     * @param commitUrl a commit URL
+     * @return the repo name ("username/reponame")
+     */
+    private static String getRepoName(String commitUrl) {
+        if (StringUtils.isBlank(commitUrl)) {
+            return null;
+        }
+        int indexOfUsername = (GitHub.GITHUB_URL + "/repos/").length();
+        String[] tokens = commitUrl.substring(indexOfUsername).split("/", 3);
+        return tokens[0] + '/' + tokens[1];
+    }
+
+    @Override
+    protected String getApiUrl() {
+        return "/search/commits";
+    }
+}

src/main/java/org/kohsuke/github/GHEvent.java

@@ -21,17 +21,30 @@ public enum GHEvent {
     FORK_APPLY,
     GIST,
     GOLLUM,
+    INSTALLATION,
+    INSTALLATION_REPOSITORIES,
     ISSUE_COMMENT,
     ISSUES,
+    LABEL,
+    MARKETPLACE_PURCHASE,
     MEMBER,
+    MEMBERSHIP,
+    MILESTONE,
+    ORGANIZATION,
+    ORG_BLOCK,
     PAGE_BUILD,
+    PROJECT_CARD,
+    PROJECT_COLUMN,
+    PROJECT,
     PUBLIC,
     PULL_REQUEST,
+    PULL_REQUEST_REVIEW,
     PULL_REQUEST_REVIEW_COMMENT,
     PUSH,
     RELEASE,
     REPOSITORY, // only valid for org hooks
     STATUS,
+    TEAM,
     TEAM_ADD,
     WATCH,
     PING,

src/main/java/org/kohsuke/github/GHHook.java

@@ -41,6 +41,13 @@ public abstract class GHHook extends GHObject {
         return Collections.unmodifiableMap(config);
     }
 
+    /**
+     * @see <a href="https://developer.github.com/v3/repos/hooks/#ping-a-hook">Ping hook</a>
+     */
+    public void ping() throws IOException {
+        new Requester(getRoot()).method("POST").to(getApiRoute() + "/pings");
+    }
+
     /**
      * Deletes this hook.
      */

src/main/java/org/kohsuke/github/GHIssueSearchBuilder.java

@@ -41,6 +41,11 @@ public class GHIssueSearchBuilder extends GHSearchBuilder<GHIssue> {
         return q("is:merged");
     }
 
+    public GHIssueSearchBuilder order(GHDirection v) {
+        req.with("order",v);
+        return this;
+    }
+
     public GHIssueSearchBuilder sort(Sort sort) {
         req.with("sort",sort);
         return this;

src/main/java/org/kohsuke/github/GHPermission.java

@@ -0,0 +1,59 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2016 CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package org.kohsuke.github;
+
+import java.util.Locale;
+
+/**
+ * Permission for a user in a repository.
+ * @see <a href="https://developer.github.com/v3/repos/collaborators/#review-a-users-permission-level">API</a>
+ */
+/*package*/ class GHPermission {
+
+    private String permission;
+    private GHUser user;
+
+    /**
+     * @return one of {@code admin}, {@code write}, {@code read}, or {@code none}
+     */
+    public String getPermission() {
+        return permission;
+    }
+
+    public GHPermissionType getPermissionType() {
+        return Enum.valueOf(GHPermissionType.class, permission.toUpperCase(Locale.ENGLISH));
+    }
+
+    public GHUser getUser() {
+        return user;
+    }
+
+    void wrapUp(GitHub root) {
+        if (user != null) {
+            user.root = root;
+        }
+    }
+
+}

src/main/java/org/kohsuke/github/GHPermissionType.java

@@ -0,0 +1,11 @@
+package org.kohsuke.github;
+
+/**
+ * @author Kohsuke Kawaguchi
+ */
+public enum GHPermissionType {
+    ADMIN,
+    WRITE,
+    READ,
+    NONE
+}

src/main/java/org/kohsuke/github/GHPerson.java

@@ -93,10 +93,10 @@ public abstract class GHPerson extends GHObject {
     }
 
     /**
-     * Loads repository list in a pagenated fashion.
+     * Loads repository list in a paginated fashion.
      * 
      * <p>
-     * For a person with a lot of repositories, GitHub returns the list of repositories in a pagenated fashion.
+     * For a person with a lot of repositories, GitHub returns the list of repositories in a paginated fashion.
      * Unlike {@link #getRepositories()}, this method allows the caller to start processing data as it arrives.
      * 
      * Every {@link Iterator#next()} call results in I/O. Exceptions that occur during the processing is wrapped

src/main/java/org/kohsuke/github/GHPullRequest.java

@@ -25,8 +25,14 @@ package org.kohsuke.github;
 
 import java.io.IOException;
 import java.net.URL;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Date;
+import java.util.List;
+import javax.annotation.CheckForNull;
+
+import static org.kohsuke.github.Previews.BLACK_CAT;
 
 /**
  * A pull request.
@@ -208,12 +214,12 @@ public class GHPullRequest extends GHIssue {
     }
 
     /**
-     * Retrieves all the commits associated to this pull request.
+     * Retrieves all the files associated to this pull request.
      */
     public PagedIterable<GHPullRequestFileDetail> listFiles() {
         return new PagedIterable<GHPullRequestFileDetail>() {
             public PagedIterator<GHPullRequestFileDetail> _iterator(int pageSize) {
-                return new PagedIterator<GHPullRequestFileDetail>(root.retrieve().asIterator(String.format("%s/files", getApiURL()),
+                return new PagedIterator<GHPullRequestFileDetail>(root.retrieve().asIterator(String.format("%s/files", getApiRoute()),
                         GHPullRequestFileDetail[].class, pageSize)) {
                     @Override
                     protected void wrapUp(GHPullRequestFileDetail[] page) {
@@ -223,6 +229,27 @@ public class GHPullRequest extends GHIssue {
         };
     }
 
+    /**
+     * Retrieves all the reviews associated to this pull request.
+     */
+    public PagedIterable<GHPullRequestReview> listReviews() {
+        return new PagedIterable<GHPullRequestReview>() {
+            public PagedIterator<GHPullRequestReview> _iterator(int pageSize) {
+                return new PagedIterator<GHPullRequestReview>(root.retrieve()
+                        .withPreview(BLACK_CAT)
+                        .asIterator(String.format("%s/reviews", getApiRoute()),
+                        GHPullRequestReview[].class, pageSize)) {
+                    @Override
+                    protected void wrapUp(GHPullRequestReview[] page) {
+                        for (GHPullRequestReview r: page) {
+                            r.wrapUp(GHPullRequest.this);
+                        }
+                    }
+                };
+            }
+        };
+    }
+
     /**
      * Obtains all the review comments associated with this pull request.
      */
@@ -247,7 +274,7 @@ public class GHPullRequest extends GHIssue {
         return new PagedIterable<GHPullRequestCommitDetail>() {
             public PagedIterator<GHPullRequestCommitDetail> _iterator(int pageSize) {
                 return new PagedIterator<GHPullRequestCommitDetail>(root.retrieve().asIterator(
-                        String.format("%s/commits", getApiURL()),
+                        String.format("%s/commits", getApiRoute()),
                         GHPullRequestCommitDetail[].class, pageSize)) {
                     @Override
                     protected void wrapUp(GHPullRequestCommitDetail[] page) {
@@ -259,6 +286,34 @@ public class GHPullRequest extends GHIssue {
         };
     }
 
+    @Preview
+    @Deprecated
+    public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event,
+                                            GHPullRequestReviewComment... comments)
+            throws IOException {
+        return createReview(body, event, Arrays.asList(comments));
+    }
+
+    @Preview
+    @Deprecated
+    public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event,
+                                            List<GHPullRequestReviewComment> comments)
+            throws IOException {
+//        if (event == null) {
+//            event = GHPullRequestReviewState.PENDING;
+//        }
+        List<DraftReviewComment> draftComments = new ArrayList<DraftReviewComment>(comments.size());
+        for (GHPullRequestReviewComment c : comments) {
+            draftComments.add(new DraftReviewComment(c.getBody(), c.getPath(), c.getPosition()));
+        }
+        return new Requester(root).method("POST")
+                .with("body", body)
+                //.with("event", event.name())
+                ._with("comments", draftComments)
+                .withPreview(BLACK_CAT)
+                .to(getApiRoute() + "/reviews", GHPullRequestReview.class).wrapUp(this);
+    }
+
     public GHPullRequestReviewComment createReviewComment(String body, String sha, String path, int position) throws IOException {
         return new Requester(root).method("POST")
                 .with("body", body)
@@ -300,4 +355,28 @@ public class GHPullRequest extends GHIssue {
             fetchedIssueDetails = true;
         }
     }
+
+    private static class DraftReviewComment {
+        private String body;
+        private String path;
+        private int position;
+
+        public DraftReviewComment(String body, String path, int position) {
+            this.body = body;
+            this.path = path;
+            this.position = position;
+        }
+
+        public String getBody() {
+            return body;
+        }
+
+        public String getPath() {
+            return path;
+        }
+
+        public int getPosition() {
+            return position;
+        }
+    }
 }

src/main/java/org/kohsuke/github/GHPullRequestReview.java

@@ -0,0 +1,149 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2017, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.kohsuke.github;
+
+import java.io.IOException;
+import java.net.URL;
+
+import static org.kohsuke.github.Previews.BLACK_CAT;
+
+/**
+ * Review to the pull request
+ *
+ * @see GHPullRequest#listReviews()
+ * @see GHPullRequest#createReview(String, GHPullRequestReviewState, GHPullRequestReviewComment...)
+ */
+public class GHPullRequestReview extends GHObject {
+    GHPullRequest owner;
+
+    private String body;
+    private GHUser user;
+    private String commit_id;
+    private GHPullRequestReviewState state;
+
+    /*package*/ GHPullRequestReview wrapUp(GHPullRequest owner) {
+        this.owner = owner;
+        return this;
+    }
+
+    /**
+     * Gets the pull request to which this review is associated.
+     */
+    public GHPullRequest getParent() {
+        return owner;
+    }
+
+    /**
+     * The comment itself.
+     */
+    public String getBody() {
+        return body;
+    }
+
+    /**
+     * Gets the user who posted this review.
+     */
+    public GHUser getUser() throws IOException {
+        return owner.root.getUser(user.getLogin());
+    }
+
+    public String getCommitId() {
+        return commit_id;
+    }
+
+    public GHPullRequestReviewState getState() {
+        return state;
+    }
+
+    @Override
+    public URL getHtmlUrl() {
+        return null;
+    }
+
+    protected String getApiRoute() {
+        return owner.getApiRoute()+"/reviews/"+id;
+    }
+
+    /**
+     * Updates the comment.
+     */
+    @Preview
+    @Deprecated
+    public void submit(String body, GHPullRequestReviewState event) throws IOException {
+        new Requester(owner.root).method("POST")
+                .with("body", body)
+                .with("event", event.action())
+                .withPreview("application/vnd.github.black-cat-preview+json")
+                .to(getApiRoute()+"/events",this);
+        this.body = body;
+        this.state = event;
+    }
+
+    /**
+     * Deletes this review.
+     */
+    @Preview
+    @Deprecated
+    public void delete() throws IOException {
+        new Requester(owner.root).method("DELETE")
+                .withPreview(BLACK_CAT)
+                .to(getApiRoute());
+    }
+
+    /**
+     * Dismisses this review.
+     */
+    @Preview
+    @Deprecated
+    public void dismiss(String message) throws IOException {
+        new Requester(owner.root).method("PUT")
+                .with("message", message)
+                .withPreview(BLACK_CAT)
+                .to(getApiRoute()+"/dismissals");
+        state = GHPullRequestReviewState.DISMISSED;
+    }
+
+    /**
+     * Obtains all the review comments associated with this pull request review.
+     */
+    @Preview
+    @Deprecated
+    public PagedIterable<GHPullRequestReviewComment> listReviewComments() throws IOException {
+        return new PagedIterable<GHPullRequestReviewComment>() {
+            public PagedIterator<GHPullRequestReviewComment> _iterator(int pageSize) {
+                return new PagedIterator<GHPullRequestReviewComment>(
+                        owner.root.retrieve()
+                                .withPreview(BLACK_CAT)
+                                .asIterator(getApiRoute() + "/comments",
+                                GHPullRequestReviewComment[].class, pageSize)) {
+                    protected void wrapUp(GHPullRequestReviewComment[] page) {
+                        for (GHPullRequestReviewComment c : page)
+                            c.wrapUp(owner);
+                    }
+                };
+            }
+        };
+    }
+
+}

src/main/java/org/kohsuke/github/GHPullRequestReviewComment.java

@@ -44,6 +44,14 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable {
     private int position;
     private int originalPosition;
 
+    public static GHPullRequestReviewComment draft(String body, String path, int position) {
+        GHPullRequestReviewComment result = new GHPullRequestReviewComment();
+        result.body = body;
+        result.path = path;
+        result.position = position;
+        return result;
+    }
+
     /*package*/ GHPullRequestReviewComment wrapUp(GHPullRequest owner) {
         this.owner = owner;
         return this;

src/main/java/org/kohsuke/github/GHPullRequestReviewState.java

@@ -0,0 +1,19 @@
+package org.kohsuke.github;
+
+public enum GHPullRequestReviewState {
+    PENDING(null),
+    APPROVED("APPROVE"),
+    REQUEST_CHANGES("REQUEST_CHANGES"),
+    COMMENTED("COMMENT"),
+    DISMISSED(null);
+
+    private final String _action;
+
+    GHPullRequestReviewState(String action) {
+        _action = action;
+    }
+
+    public String action() {
+        return _action;
+    }
+}

src/main/java/org/kohsuke/github/GHRelease.java

@@ -121,9 +121,7 @@ public class GHRelease extends GHObject {
      * Java 7 or greater.  Options for fixing this for earlier JVMs can be found here
      * http://stackoverflow.com/questions/12361090/server-name-indication-sni-on-java but involve more complicated
      * handling of the HTTP requests to github's API.
-     *
-     * @throws IOException
-     */
+         */
     public GHAsset uploadAsset(File file, String contentType) throws IOException {
         Requester builder = new Requester(owner.root);
 

src/main/java/org/kohsuke/github/GHReleaseBuilder.java

@@ -33,7 +33,6 @@ public class GHReleaseBuilder {
      *
      * @param commitish Defaults to the repository’s default branch (usually "master"). Unused if the Git tag
      *                  already exists.
-     * @return
      */
     public GHReleaseBuilder commitish(String commitish) {
         if (commitish != null) {

src/main/java/org/kohsuke/github/GHRepository.java

@@ -31,6 +31,7 @@ import org.apache.commons.lang.StringUtils;
 
 import java.io.FileNotFoundException;
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.InputStreamReader;
 import java.io.InterruptedIOException;
 import java.io.Reader;
@@ -59,7 +60,7 @@ import static org.kohsuke.github.Previews.*;
  * @author Kohsuke Kawaguchi
  */
 @SuppressWarnings({"UnusedDeclaration"})
-@SuppressFBWarnings(value = {"UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", 
+@SuppressFBWarnings(value = {"UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD",
     "NP_UNWRITTEN_FIELD"}, justification = "JSON API")
 public class GHRepository extends GHObject {
     /*package almost final*/ GitHub root;
@@ -297,6 +298,14 @@ public class GHRepository extends GHObject {
     public List<GHRelease> getReleases() throws IOException {
         return listReleases().asList();
     }
+    
+    public GHRelease getLatestRelease() throws IOException {
+        try {
+            return root.retrieve().to(getApiTailUrl("releases/latest"), GHRelease.class).wrap(this);
+        } catch (FileNotFoundException e) {
+            return null; // no latest release
+        }
+    }
 
     public PagedIterable<GHRelease> listReleases() throws IOException {
         return new PagedIterable<GHRelease>() {
@@ -433,8 +442,8 @@ public class GHRepository extends GHObject {
     public int getSize() {
         return size;
     }
-    
-   
+
+
     /**
      * Gets the collaborators on this repository.
      * This set always appear to include the owner.
@@ -448,7 +457,6 @@ public class GHRepository extends GHObject {
      * Lists up the collaborators on this repository.
      *
      * @return Users
-     * @throws IOException
      */
     public PagedIterable<GHUser> listCollaborators() throws IOException {
         return listUsers("collaborators");
@@ -480,6 +488,27 @@ public class GHRepository extends GHObject {
         return r;
     }
 
+    /**
+     * Obtain permission for a given user in this repository.
+     * @param user a {@link GHUser#getLogin}
+     * @throws FileNotFoundException under some conditions (e.g., private repo you can see but are not an admin of); treat as unknown
+     * @throws HttpException with a 403 under other conditions (e.g., public repo you have no special rights to); treat as unknown
+     */
+    public GHPermissionType getPermission(String user) throws IOException {
+        GHPermission perm = root.retrieve().to(getApiTailUrl("collaborators/" + user + "/permission"), GHPermission.class);
+        perm.wrapUp(root);
+        return perm.getPermissionType();
+    }
+
+    /**
+     * Obtain permission for a given user in this repository.
+     * @throws FileNotFoundException under some conditions (e.g., private repo you can see but are not an admin of); treat as unknown
+     * @throws HttpException with a 403 under other conditions (e.g., public repo you have no special rights to); treat as unknown
+     */
+    public GHPermissionType getPermission(GHUser u) throws IOException {
+        return getPermission(u.getLogin());
+    }
+
     /**
      * If this repository belongs to an organization, return a set of teams.
      */
@@ -504,7 +533,6 @@ public class GHRepository extends GHObject {
     }
 
     private void modifyCollaborators(Collection<GHUser> users, String method) throws IOException {
-        verifyMine();
         for (GHUser user : users) {
             new Requester(root).method(method).to(getApiTailUrl("collaborators/" + user.getLogin()));
         }
@@ -762,6 +790,26 @@ public class GHRepository extends GHObject {
        return GHRef.wrap(root.retrieve().to(String.format("/repos/%s/%s/git/refs", getOwnerName(), name), GHRef[].class), root);
     }
 
+
+    /**
+     * Retrieves all refs for the github repository.
+     *
+     * @return paged iterable of all refs
+     * @throws IOException on failure communicating with GitHub, potentially due to an invalid ref type being requested
+     */
+    public PagedIterable<GHRef> listRefs() throws IOException {
+        final String url = String.format("/repos/%s/%s/git/refs", getOwnerName(), name);
+        return new PagedIterable<GHRef>() {
+            public PagedIterator<GHRef> _iterator(int pageSize) {
+                return new PagedIterator<GHRef>(root.retrieve().asIterator(url, GHRef[].class, pageSize)) {
+                    protected void wrapUp(GHRef[] page) {
+                        // no-op
+                    }
+                };
+            }
+        };
+    }
+
     /**
      * Retrieves all refs of the given type for the current GitHub repository.
      * @param refType the type of reg to search for e.g. <tt>tags</tt> or <tt>commits</tt>
@@ -771,6 +819,27 @@ public class GHRepository extends GHObject {
     public GHRef[] getRefs(String refType) throws IOException {
         return GHRef.wrap(root.retrieve().to(String.format("/repos/%s/%s/git/refs/%s", getOwnerName(), name, refType), GHRef[].class),root);
     }
+
+    /**
+     * Retrieves all refs of the given type for the current GitHub repository.
+     *
+     * @param refType the type of reg to search for e.g. <tt>tags</tt> or <tt>commits</tt>
+     * @return paged iterable of all refs of the specified type
+     * @throws IOException on failure communicating with GitHub, potentially due to an invalid ref type being requested
+     */
+    public PagedIterable<GHRef> listRefs(String refType) throws IOException {
+        final String url = String.format("/repos/%s/%s/git/refs/%s", getOwnerName(), name, refType);
+        return new PagedIterable<GHRef>() {
+            public PagedIterator<GHRef> _iterator(int pageSize) {
+                return new PagedIterator<GHRef>(root.retrieve().asIterator(url, GHRef[].class, pageSize)) {
+                    protected void wrapUp(GHRef[] page) {
+                        // no-op
+                    }
+                };
+            }
+        };
+    }
+
     /**
      * Retrive a ref of the given type for the current GitHub repository.
      *
@@ -788,6 +857,18 @@ public class GHRepository extends GHObject {
         refName = refName.replaceAll("#", "%23");
         return root.retrieve().to(String.format("/repos/%s/%s/git/refs/%s", getOwnerName(), name, refName), GHRef.class).wrap(root);
     }
+
+    /**
+     * Returns the <strong>annotated</strong> tag object. Only valid if the {@link GHRef#getObject()} has a
+     * {@link GHRef.GHObject#getType()} of {@code tag}.
+     *
+     * @param sha the sha of the tag object
+     * @return the annotated tag object
+     */
+    public GHTagObject getTagObject(String sha) throws IOException {
+        return root.retrieve().to(getApiTailUrl("git/tags/" + sha), GHTagObject.class).wrap(this);
+    }
+    
     /**
      * Retrive a tree of the given type for the current GitHub repository.
      *
@@ -799,7 +880,7 @@ public class GHRepository extends GHObject {
      */
     public GHTree getTree(String sha) throws IOException {
         String url = String.format("/repos/%s/%s/git/trees/%s", getOwnerName(), name, sha);
-        return root.retrieve().to(url, GHTree.class).wrap(root);
+        return root.retrieve().to(url, GHTree.class).wrap(this);
     }
 
     /**
@@ -814,7 +895,32 @@ public class GHRepository extends GHObject {
      */
     public GHTree getTreeRecursive(String sha, int recursive) throws IOException {
         String url = String.format("/repos/%s/%s/git/trees/%s?recursive=%d", getOwnerName(), name, sha, recursive);
-        return root.retrieve().to(url, GHTree.class).wrap(root);
+        return root.retrieve().to(url, GHTree.class).wrap(this);
+    }
+
+    /**
+     * Obtains the metadata &amp; the content of a blob.
+     *
+     * <p>
+     * This method retrieves the whole content in memory, so beware when you are dealing with large BLOB.
+     *
+     * @see <a href="https://developer.github.com/v3/git/blobs/#get-a-blob">Get a blob</a>
+     * @see #readBlob(String)
+     */
+    public GHBlob getBlob(String blobSha) throws IOException {
+        String target = getApiTailUrl("git/blobs/" + blobSha);
+        return root.retrieve().to(target, GHBlob.class);
+    }
+
+    /**
+     * Reads the content of a blob as a stream for better efficiency.
+     *
+     * @see <a href="https://developer.github.com/v3/git/blobs/#get-a-blob">Get a blob</a>
+     * @see #getBlob(String)
+     */
+    public InputStream readBlob(String blobSha) throws IOException {
+        String target = getApiTailUrl("git/blobs/" + blobSha);
+        return root.retrieve().withHeader("Accept","application/vnd.github.VERSION.raw").asStream(target);
     }
 
     /**
@@ -1092,11 +1198,6 @@ public class GHRepository extends GHObject {
 //        return root.retrieveWithAuth("/pulls/"+owner+'/'+name,JsonPullRequests.class).wrap(root);
 //    }
 
-    private void verifyMine() throws IOException {
-        if (!root.login.equals(getOwnerName()))
-            throw new IOException("Operation not applicable to a repository owned by someone else: " + getOwnerName());
-    }
-
     /**
      * Returns a set that represents the post-commit hook URLs.
      * The returned set is live, and changes made to them are reflected to GitHub.
@@ -1104,7 +1205,7 @@ public class GHRepository extends GHObject {
      * @deprecated
      *      Use {@link #getHooks()} and {@link #createHook(String, Map, Collection, boolean)}
      */
-    @SuppressFBWarnings(value = "DMI_COLLECTION_OF_URLS", 
+    @SuppressFBWarnings(value = "DMI_COLLECTION_OF_URLS",
             justification = "It causes a performance degradation, but we have already exposed it to the API")
     public Set<URL> getPostCommitHooks() {
         return postCommitHooks;
@@ -1113,7 +1214,7 @@ public class GHRepository extends GHObject {
     /**
      * Live set view of the post-commit hook.
      */
-    @SuppressFBWarnings(value = "DMI_COLLECTION_OF_URLS", 
+    @SuppressFBWarnings(value = "DMI_COLLECTION_OF_URLS",
             justification = "It causes a performance degradation, but we have already exposed it to the API")
     @SkipFromToString
     private final Set<URL> postCommitHooks = new AbstractSet<URL>() {
@@ -1181,7 +1282,7 @@ public class GHRepository extends GHObject {
      */
     public Map<String,GHBranch> getBranches() throws IOException {
         Map<String,GHBranch> r = new TreeMap<String,GHBranch>();
-        for (GHBranch p : root.retrieve().to(getApiTailUrl("branches"), GHBranch[].class)) {
+        for (GHBranch p : root.retrieve().withPreview(LOKI).to(getApiTailUrl("branches"), GHBranch[].class)) {
             p.wrap(this);
             r.put(p.getName(),p);
         }
@@ -1189,7 +1290,7 @@ public class GHRepository extends GHObject {
     }
 
     public GHBranch getBranch(String name) throws IOException {
-        return root.retrieve().to(getApiTailUrl("branches/"+name),GHBranch.class).wrap(this);
+        return root.retrieve().withPreview(LOKI).to(getApiTailUrl("branches/"+name),GHBranch.class).wrap(this);
     }
 
     /**
@@ -1411,7 +1512,7 @@ public class GHRepository extends GHObject {
         public boolean equals(Object obj) {
             // We ignore contributions in the calculation
             return super.equals(obj);
-        }   
+        }
     }
 
     /**

src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java

@@ -57,6 +57,11 @@ public class GHRepositorySearchBuilder extends GHSearchBuilder<GHRepository> {
         return q("stars:"+v);
     }
 
+    public GHRepositorySearchBuilder order(GHDirection v) {
+        req.with("order",v);
+        return this;
+    }
+
     public GHRepositorySearchBuilder sort(Sort sort) {
         req.with("sort",sort);
         return this;

src/main/java/org/kohsuke/github/GHTagObject.java

@@ -0,0 +1,60 @@
+package org.kohsuke.github;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+/**
+ * Represents an annotated tag in a {@link GHRepository}
+ *
+ * @see GHRepository#getAnnotatedTag()
+ */
+@SuppressFBWarnings(value = {"UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", 
+    "NP_UNWRITTEN_FIELD"}, justification = "JSON API")
+public class GHTagObject {
+    private GHRepository owner;
+    private GitHub root;
+
+    private String tag;
+    private String sha;
+    private String url;
+    private String message;
+    private GitUser tagger;
+    private GHRef.GHObject object;
+
+    /*package*/ GHTagObject wrap(GHRepository owner) {
+        this.owner = owner;
+        this.root = owner.root;
+        return this;
+    }
+
+    public GHRepository getOwner() {
+        return owner;
+    }
+
+    public GitHub getRoot() {
+        return root;
+    }
+
+    public String getTag() {
+        return tag;
+    }
+
+    public String getSha() {
+        return sha;
+    }
+
+    public String getUrl() {
+        return url;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public GitUser getTagger() {
+        return tagger;
+    }
+
+    public GHRef.GHObject getObject() {
+        return object;
+    }
+}

src/main/java/org/kohsuke/github/GHTree.java

@@ -10,10 +10,12 @@ import java.util.List;
  * https://developer.github.com/v3/git/trees/
  *
  * @author Daniel Teixeira - https://github.com/ddtxra
+ * @see GHCommit#getTree()
  * @see GHRepository#getTree(String)
+ * @see GHTreeEntry#asTree()
  */
 public class GHTree {
-    /* package almost final */GitHub root;
+    /* package almost final */GHRepository repo;
 
     private boolean truncated;
     private String sha, url;
@@ -28,12 +30,24 @@ public class GHTree {
 
     /**
      * Return an array of entries of the trees
-     * @return
      */
     public List<GHTreeEntry> getTree() {
         return Collections.unmodifiableList(Arrays.asList(tree));
     }
 
+    /**
+     * Finds a tree entry by its name.
+     *
+     * IOW, find a directory entry by a file name.
+     */
+    public GHTreeEntry getEntry(String path) {
+        for (GHTreeEntry e : tree) {
+            if (e.getPath().equals(path))
+                return e;
+        }
+        return null;
+    }
+
     /**
      * Returns true if the number of items in the tree array exceeded the GitHub maximum limit. 
      * @return true true if the number of items in the tree array exceeded the GitHub maximum limit otherwise false.
@@ -50,8 +64,11 @@ public class GHTree {
         return GitHub.parseURL(url);
     }
 
-    /* package */GHTree wrap(GitHub root) {
-        this.root = root;
+    /* package */GHTree wrap(GHRepository repo) {
+        this.repo = repo;
+        for (GHTreeEntry e : tree) {
+            e.tree = this;
+        }
         return this;
     }
 

src/main/java/org/kohsuke/github/GHTreeEntry.java

@@ -1,5 +1,7 @@
 package org.kohsuke.github;
 
+import java.io.IOException;
+import java.io.InputStream;
 import java.net.URL;
 
 /**
@@ -10,6 +12,8 @@ import java.net.URL;
  * @see GHTree
  */
 public class GHTreeEntry {
+    /* package almost final */GHTree tree;
+
     private String path, mode, type, sha, url;
     private long size;
 
@@ -44,7 +48,7 @@ public class GHTreeEntry {
 
     /**
      * Gets the type such as:
-     * "blob"
+     * "blob", "tree", etc.
      *
      * @return The type
      */
@@ -68,4 +72,37 @@ public class GHTreeEntry {
     public URL getUrl() {
         return GitHub.parseURL(url);
     }
+
+    /**
+     * If this tree entry represents a file, then return its information.
+     * Otherwise null.
+     */
+    public GHBlob asBlob() throws IOException {
+        if (type.equals("blob"))
+            return tree.repo.getBlob(sha);
+        else
+            return null;
+    }
+
+    /**
+     * If this tree entry represents a file, then return its content.
+     * Otherwise null.
+     */
+    public InputStream readAsBlob() throws IOException {
+        if (type.equals("blob"))
+            return tree.repo.readBlob(sha);
+        else
+            return null;
+    }
+
+    /**
+     * If this tree entry represents a directory, then return it.
+     * Otherwise null.
+     */
+    public GHTree asTree() throws IOException {
+        if (type.equals("tree"))
+            return tree.repo.getTree(sha);
+        else
+            return null;
+    }
 }

src/main/java/org/kohsuke/github/GHUserSearchBuilder.java

@@ -49,6 +49,11 @@ public class GHUserSearchBuilder extends GHSearchBuilder<GHUser> {
         return q("followers:"+v);
     }
 
+    public GHUserSearchBuilder order(GHDirection v) {
+        req.with("order",v);
+        return this;
+    }
+
     public GHUserSearchBuilder sort(Sort sort) {
         req.with("sort",sort);
         return this;

src/main/java/org/kohsuke/github/GitHub.java

@@ -23,12 +23,10 @@
  */
 package org.kohsuke.github;
 
-import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.ANY;
-import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.NONE;
-import static java.util.logging.Level.FINE;
-import static java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
-import static org.kohsuke.github.Previews.DRAX;
-
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.introspect.VisibilityChecker.Std;
+import com.infradna.tool.bridge_method_injector.WithBridgeMethods;
 import java.io.ByteArrayInputStream;
 import java.io.FileNotFoundException;
 import java.io.IOException;
@@ -49,17 +47,18 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.TimeZone;
-
+import java.util.logging.Logger;
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 import org.apache.commons.codec.Charsets;
 import org.apache.commons.codec.binary.Base64;
+import org.apache.commons.io.IOUtils;
 
-import com.fasterxml.jackson.databind.DeserializationFeature;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.introspect.VisibilityChecker.Std;
-import com.infradna.tool.bridge_method_injector.WithBridgeMethods;
-
-import javax.annotation.Nonnull;
-import java.util.logging.Logger;
+import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.ANY;
+import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.NONE;
+import static java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
+import static java.util.logging.Level.FINE;
+import static org.kohsuke.github.Previews.DRAX;
 
 /**
  * Root of the GitHub API.
@@ -90,6 +89,10 @@ public class GitHub {
 
     private HttpConnector connector = HttpConnector.DEFAULT;
 
+    private final Object headerRateLimitLock = new Object();
+    private GHRateLimit headerRateLimit = null;
+    private volatile GHRateLimit rateLimit = null;
+
     /**
      * Creates a client API root object.
      *
@@ -254,6 +257,10 @@ public class GitHub {
         return connector;
     }
 
+    public String getApiUrl() {
+        return apiUrl;
+    }
+
     /**
      * Sets the custom connector used to make requests to GitHub.
      */
@@ -287,19 +294,63 @@ public class GitHub {
      */
     public GHRateLimit getRateLimit() throws IOException {
         try {
-            return retrieve().to("/rate_limit", JsonRateLimit.class).rate;
+            return rateLimit = retrieve().to("/rate_limit", JsonRateLimit.class).rate;
         } catch (FileNotFoundException e) {
             // GitHub Enterprise doesn't have the rate limit, so in that case
             // return some big number that's not too big.
             // see issue #78
             GHRateLimit r = new GHRateLimit();
             r.limit = r.remaining = 1000000;
-            long hours = 1000L * 60 * 60;
-            r.reset = new Date(System.currentTimeMillis() + 1 * hours );
-            return r;
+            long hour = 60L * 60L; // this is madness, storing the date as seconds in a Date object
+            r.reset = new Date(System.currentTimeMillis() / 1000L + hour);
+            return rateLimit = r;
         }
     }
 
+    /*package*/ void updateRateLimit(@Nonnull GHRateLimit observed) {
+        synchronized (headerRateLimitLock) {
+            if (headerRateLimit == null
+                    || headerRateLimit.getResetDate().getTime() < observed.getResetDate().getTime()
+                    || headerRateLimit.remaining > observed.remaining) {
+                headerRateLimit = observed;
+                LOGGER.log(FINE, "Rate limit now: {0}", headerRateLimit);
+            }
+        }
+    }
+
+    /**
+     * Returns the most recently observed rate limit data or {@code null} if either there is no rate limit
+     * (for example GitHub Enterprise) or if no requests have been made.
+     *
+     * @return the most recently observed rate limit data or {@code null}.
+     */
+    @CheckForNull
+    public GHRateLimit lastRateLimit() {
+        synchronized (headerRateLimitLock) {
+            return headerRateLimit;
+        }
+    }
+
+    /**
+     * Gets the current rate limit while trying not to actually make any remote requests unless absolutely necessary.
+     *
+     * @return the current rate limit data.
+     * @throws IOException if we couldn't get the current rate limit data.
+     */
+    @Nonnull
+    public GHRateLimit rateLimit() throws IOException {
+        synchronized (headerRateLimitLock) {
+            if (headerRateLimit != null) {
+                return headerRateLimit;
+            }
+        }
+        GHRateLimit rateLimit = this.rateLimit;
+        if (rateLimit == null || rateLimit.getResetDate().getTime() < System.currentTimeMillis()) {
+            rateLimit = getRateLimit();
+        }
+        return rateLimit;
+    }
+
     /**
      * Gets the {@link GHUser} that represents yourself.
      */
@@ -416,7 +467,6 @@ public class GitHub {
      *
      * @param key The license key provided from the API
      * @return The license details
-     * @throws IOException
      * @see GHLicense#getKey()
      */
     @Preview @Deprecated
@@ -652,13 +702,31 @@ public class GitHub {
                 Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
                 X-Content-Type-Options: nosniff
              */
-            return uc.getResponseCode() == HTTP_UNAUTHORIZED
-                && uc.getHeaderField("X-GitHub-Media-Type") != null;
+            try {
+                return uc.getResponseCode() == HTTP_UNAUTHORIZED
+                        && uc.getHeaderField("X-GitHub-Media-Type") != null;
+            } finally {
+                // ensure that the connection opened by getResponseCode gets closed
+                try {
+                    IOUtils.closeQuietly(uc.getInputStream());
+                } catch (IOException ignore) {
+                    // ignore
+                }
+                IOUtils.closeQuietly(uc.getErrorStream());
+            }
         } catch (IOException e) {
             return false;
         }
     }
 
+    /**
+     * Search commits.
+     */
+    @Preview @Deprecated
+    public GHCommitSearchBuilder searchCommits() {
+        return new GHCommitSearchBuilder(this);
+    }
+
     /**
      * Search issues.
      */

src/main/java/org/kohsuke/github/PagedIterator.java

@@ -6,7 +6,7 @@ import java.util.List;
 import java.util.NoSuchElementException;
 
 /**
- * Iterator over a pagenated data source.
+ * Iterator over a paginated data source.
  *
  * Aside from the normal iterator operation, this method exposes {@link #nextPage()}
  * that allows the caller to retrieve items per page.

src/main/java/org/kohsuke/github/Previews.java

@@ -7,4 +7,6 @@ package org.kohsuke.github;
     static final String LOKI = "application/vnd.github.loki-preview+json";
     static final String DRAX = "application/vnd.github.drax-preview+json";
     static final String SQUIRREL_GIRL = "application/vnd.github.squirrel-girl-preview";
+    static final String CLOAK = "application/vnd.github.cloak-preview";
+    static final String BLACK_CAT = "application/vnd.github.black-cat-preview+json";
 }

src/main/java/org/kohsuke/github/Requester.java

@@ -25,8 +25,6 @@ package org.kohsuke.github;
 
 import com.fasterxml.jackson.databind.JsonMappingException;
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
-import org.apache.commons.io.IOUtils;
-
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
@@ -38,10 +36,12 @@ import java.lang.reflect.Field;
 import java.net.HttpURLConnection;
 import java.net.MalformedURLException;
 import java.net.ProtocolException;
+import java.net.SocketTimeoutException;
 import java.net.URL;
 import java.net.URLEncoder;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
@@ -53,12 +53,14 @@ import java.util.logging.Logger;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.zip.GZIPInputStream;
-
 import javax.annotation.WillClose;
+import org.apache.commons.io.IOUtils;
+import org.apache.commons.lang.StringUtils;
 
 import static java.util.Arrays.asList;
-import static java.util.logging.Level.FINE;
-import static org.kohsuke.github.GitHub.*;
+import java.util.logging.Level;
+import static java.util.logging.Level.*;
+import static org.kohsuke.github.GitHub.MAPPER;
 
 /**
  * A builder pattern for making HTTP call and parsing its output.
@@ -168,6 +170,11 @@ class Requester {
         return this;
     }
 
+	public Requester withNullable(String key, Object value) {
+		args.add(new Entry(key, value));
+		return this;
+	}
+
     public Requester _with(String key, Object value) {
         if (value!=null) {
             args.add(new Entry(key,value));
@@ -281,6 +288,8 @@ class Requester {
                 return result;
             } catch (IOException e) {
                 handleApiError(e);
+            } finally {
+                noteRateLimit(tailApiUrl);
             }
         }
     }
@@ -299,6 +308,8 @@ class Requester {
                 return uc.getResponseCode();
             } catch (IOException e) {
                 handleApiError(e);
+            } finally {
+                noteRateLimit(tailApiUrl);
             }
         }
     }
@@ -308,11 +319,64 @@ class Requester {
             setupConnection(root.getApiURL(tailApiUrl));
 
             buildRequest();
-         
+
             try {
                 return wrapStream(uc.getInputStream());
             } catch (IOException e) {
                 handleApiError(e);
+            } finally {
+                noteRateLimit(tailApiUrl);
+            }
+        }
+    }
+
+    private void noteRateLimit(String tailApiUrl) {
+        if ("/rate_limit".equals(tailApiUrl)) {
+            // the rate_limit API is "free"
+            return;
+        }
+        if (tailApiUrl.startsWith("/search")) {
+            // the search API uses a different rate limit
+            return;
+        }
+        String limit = uc.getHeaderField("X-RateLimit-Limit");
+        if (StringUtils.isBlank(limit)) {
+            // if we are missing a header, return fast
+            return;
+        }
+        String remaining = uc.getHeaderField("X-RateLimit-Remaining");
+        if (StringUtils.isBlank(remaining)) {
+            // if we are missing a header, return fast
+            return;
+        }
+        String reset = uc.getHeaderField("X-RateLimit-Reset");
+        if (StringUtils.isBlank(reset)) {
+            // if we are missing a header, return fast
+            return;
+        }
+        GHRateLimit observed = new GHRateLimit();
+        try {
+            observed.limit = Integer.parseInt(limit);
+        } catch (NumberFormatException e) {
+            if (LOGGER.isLoggable(FINEST)) {
+                LOGGER.log(FINEST, "Malformed X-RateLimit-Limit header value " + limit, e);
+            }
+            return;
+        }
+        try {
+            observed.remaining = Integer.parseInt(remaining);
+        } catch (NumberFormatException e) {
+            if (LOGGER.isLoggable(FINEST)) {
+                LOGGER.log(FINEST, "Malformed X-RateLimit-Remaining header value " + remaining, e);
+            }
+            return;
+        }
+        try {
+            observed.reset = new Date(Long.parseLong(reset)); // this is madness, storing the date as seconds
+            root.updateRateLimit(observed);
+        } catch (NumberFormatException e) {
+            if (LOGGER.isLoggable(FINEST)) {
+                LOGGER.log(FINEST, "Malformed X-RateLimit-Reset header value " + reset, e);
             }
         }
     }
@@ -355,7 +419,7 @@ class Requester {
     }
 
     /**
-     * Loads pagenated resources.
+     * Loads paginated resources.
      *
      * Every iterator call reports a new batch.
      */
@@ -382,7 +446,7 @@ class Requester {
         }
 
         try {
-            return new PagingIterator<T>(type, root.getApiURL(s.toString()));
+            return new PagingIterator<T>(type, tailApiUrl, root.getApiURL(s.toString()));
         } catch (IOException e) {
             throw new Error(e);
         }
@@ -391,6 +455,7 @@ class Requester {
     class PagingIterator<T> implements Iterator<T> {
 
         private final Class<T> type;
+        private final String tailApiUrl;
 
         /**
          * The next batch to be returned from {@link #next()}.
@@ -402,9 +467,10 @@ class Requester {
          */
         private URL url;
 
-        PagingIterator(Class<T> type, URL url) {
-            this.url = url;
+        PagingIterator(Class<T> type, String tailApiUrl, URL url) {
             this.type = type;
+            this.tailApiUrl = tailApiUrl;
+            this.url = url;
         }
 
         public boolean hasNext() {
@@ -438,6 +504,8 @@ class Requester {
                         return;
                     } catch (IOException e) {
                         handleApiError(e);
+                    } finally {
+                        noteRateLimit(tailApiUrl);
                     }
                 }
             } catch (IOException e) {
@@ -518,6 +586,10 @@ class Requester {
     }
 
     private <T> T parse(Class<T> type, T instance) throws IOException {
+        return parse(type, instance, 2);
+    }
+
+    private <T> T parse(Class<T> type, T instance, int timeouts) throws IOException {
         InputStreamReader r = null;
         int responseCode = -1;
         String responseMessage = null;
@@ -548,6 +620,10 @@ class Requester {
             // to preserve backward compatibility
             throw e;
         } catch (IOException e) {
+            if (e instanceof SocketTimeoutException && timeouts > 0) {
+                LOGGER.log(Level.INFO, "timed out accessing " + uc.getURL() + "; will try " + timeouts + " more time(s)", e);
+                return parse(type, instance, timeouts - 1);
+            }
             throw new HttpException(responseCode, responseMessage, uc.getURL(), e);
         } finally {
             IOUtils.closeQuietly(r);
@@ -580,6 +656,24 @@ class Requester {
                         " handling exception " + e, e);
             throw e;
         }
+        InputStream es = wrapStream(uc.getErrorStream());
+        if (es != null) {
+            try {
+                String error = IOUtils.toString(es, "UTF-8");
+                if (e instanceof FileNotFoundException) {
+                    // pass through 404 Not Found to allow the caller to handle it intelligently
+                    e = (IOException) new FileNotFoundException(error).initCause(e);
+                } else if (e instanceof HttpException) {
+                    HttpException http = (HttpException) e;
+                    e = new HttpException(error, http.getResponseCode(), http.getResponseMessage(),
+                            http.getUrl(), e);
+                } else {
+                    e = (IOException) new IOException(error).initCause(e);
+                }
+            } finally {
+                IOUtils.closeQuietly(es);
+            }
+        }
         if (responseCode == HttpURLConnection.HTTP_UNAUTHORIZED) // 401 / Unauthorized == bad creds
             throw e;
 
@@ -595,19 +689,7 @@ class Requester {
             return;
         }
 
-        InputStream es = wrapStream(uc.getErrorStream());
-        try {
-            if (es!=null) {
-                if (e instanceof FileNotFoundException) {
-                    // pass through 404 Not Found to allow the caller to handle it intelligently
-                    throw (IOException) new FileNotFoundException(IOUtils.toString(es, "UTF-8")).initCause(e);
-                } else
-                    throw (IOException) new IOException(IOUtils.toString(es, "UTF-8")).initCause(e);
-            } else
-                throw e;
-        } finally {
-            IOUtils.closeQuietly(es);
-        }
+        throw e;
     }
 
     private static final List<String> METHODS_WITHOUT_BODY = asList("GET", "DELETE");

src/test/java/org/kohsuke/github/AbstractGitHubApiTestBase.java

@@ -1,10 +1,15 @@
 package org.kohsuke.github;
 
+import java.io.FileInputStream;
+import java.util.Properties;
+import org.apache.commons.io.IOUtils;
 import org.junit.Assert;
+import org.junit.Assume;
 import org.junit.Before;
 import org.kohsuke.randname.RandomNameGenerator;
 
 import java.io.File;
+import java.io.IOException;
 
 /**
  * @author Kohsuke Kawaguchi
@@ -17,13 +22,34 @@ public abstract class AbstractGitHubApiTestBase extends Assert {
     public void setUp() throws Exception {
         File f = new File(System.getProperty("user.home"), ".github.kohsuke2");
         if (f.exists()) {
+            Properties props = new Properties();
+            FileInputStream in = null;
+            try {
+                in = new FileInputStream(f);
+                props.load(in);
+            } finally {
+                IOUtils.closeQuietly(in);
+            }
             // use the non-standard credential preferentially, so that developers of this library do not have
             // to clutter their event stream.
-            gitHub = GitHubBuilder.fromPropertyFile(f.getPath()).withRateLimitHandler(RateLimitHandler.FAIL).build();
+            gitHub = GitHubBuilder.fromProperties(props).withRateLimitHandler(RateLimitHandler.FAIL).build();
         } else {
             gitHub = GitHubBuilder.fromCredentials().withRateLimitHandler(RateLimitHandler.FAIL).build();
         }
     }
 
+    protected GHUser getUser() {
+        try {
+            return gitHub.getMyself();
+        } catch (IOException e) {
+            throw new RuntimeException(e.getMessage(), e);
+        }
+    }
+
+    protected void kohsuke() {
+        String login = getUser().getLogin();
+        Assume.assumeTrue(login.equals("kohsuke") || login.equals("kohsuke2"));
+    }
+
     protected static final RandomNameGenerator rnd = new RandomNameGenerator();
 }

src/test/java/org/kohsuke/github/AppTest.java

@@ -12,6 +12,7 @@ import org.kohsuke.github.GHCommit.File;
 import org.kohsuke.github.GHOrganization.Permission;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.net.URL;
 import java.util.*;
 import java.util.Map.Entry;
@@ -172,14 +173,6 @@ public class AppTest extends AbstractGitHubApiTestBase {
         return repository;
     }
 
-    private GHUser getUser() {
-        try {
-            return gitHub.getMyself();
-        } catch (IOException e) {
-            throw new RuntimeException(e.getMessage(), e);
-        }
-    }
-
     @Test
     public void testListIssues() throws IOException {
         GHUser u = getUser();
@@ -362,6 +355,11 @@ public class AppTest extends AbstractGitHubApiTestBase {
         assertEquals(48,f.getLinesChanged());
         assertEquals("modified",f.getStatus());
         assertEquals("changelog.html", f.getFileName());
+
+        // walk the tree
+        GHTree t = commit.getTree();
+        assertThat(IOUtils.toString(t.getEntry("todo.txt").readAsBlob()), containsString("executor rendering"));
+        assertNotNull(t.getEntry("war").asTree());
     }
 
     @Test
@@ -687,6 +685,15 @@ public class AppTest extends AbstractGitHubApiTestBase {
         assertFalse(all.isEmpty());
     }
 
+    @Test
+    public void testCommitSearch() throws IOException {
+        PagedSearchIterable<GHCommit> r = gitHub.searchCommits().author("kohsuke").list();
+        assertTrue(r.getTotalCount() > 0);
+        
+        GHCommit firstCommit = r.iterator().next();
+        assertTrue(firstCommit.getFiles().size() > 0);
+    }
+
     @Test
     public void testIssueSearch() throws IOException {
         PagedSearchIterable<GHIssue> r = gitHub.searchIssues().mentions("kohsuke").isOpen().list();
@@ -903,8 +910,23 @@ public class AppTest extends AbstractGitHubApiTestBase {
         }
     }
 
-    private void kohsuke() {
-        String login = getUser().getLogin();
-        Assume.assumeTrue(login.equals("kohsuke") || login.equals("kohsuke2"));
+    @Test
+    public void blob() throws Exception {
+        GHRepository r = gitHub.getRepository("kohsuke/github-api");
+        String sha1 = "a12243f2fc5b8c2ba47dd677d0b0c7583539584d";
+
+        assertBlobContent(r.readBlob(sha1));
+
+        GHBlob blob = r.getBlob(sha1);
+        assertBlobContent(blob.read());
+        assertThat(blob.getSha(),is("a12243f2fc5b8c2ba47dd677d0b0c7583539584d"));
+        assertThat(blob.getSize(),is(1104L));
+    }
+
+    private void assertBlobContent(InputStream is) throws Exception {
+        String content = new String(IOUtils.toByteArray(is),"UTF-8");
+        assertThat(content,containsString("Copyright (c) 2011- Kohsuke Kawaguchi and other contributors"));
+        assertThat(content,containsString("FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR"));
+        assertThat(content.length(),is(1104));
     }
 }

src/test/java/org/kohsuke/github/GHBranchProtectionTest.java

@@ -0,0 +1,82 @@
+package org.kohsuke.github;
+
+import org.junit.Before;
+import org.junit.Test;
+import org.kohsuke.github.GHBranchProtection.EnforceAdmins;
+import org.kohsuke.github.GHBranchProtection.RequiredReviews;
+import org.kohsuke.github.GHBranchProtection.RequiredStatusChecks;
+
+import java.io.FileNotFoundException;
+
+public class GHBranchProtectionTest extends AbstractGitHubApiTestBase {
+    private static final String BRANCH = "bp-test";
+    private static final String BRANCH_REF = "heads/" + BRANCH;
+
+    private GHBranch branch;
+
+    private GHRepository repo;
+
+    @Before
+    @Override
+    public void setUp() throws Exception {
+        super.setUp();
+
+        repo = gitHub.getRepository("github-api-test-org/GHContentIntegrationTest").fork();
+
+        try {
+            repo.getRef(BRANCH_REF);
+        } catch (FileNotFoundException e) {
+            repo.createRef("refs/" + BRANCH_REF, repo.getBranch("master").getSHA1());
+        }
+
+        branch = repo.getBranch(BRANCH);
+
+        if (branch.isProtected()) {
+            branch.disableProtection();
+        }
+
+        branch = repo.getBranch(BRANCH);
+        assertFalse(branch.isProtected());
+    }
+
+    @Test
+    public void testEnableBranchProtections() throws Exception {
+        // team/user restrictions require an organization repo to test against
+        GHBranchProtection protection = branch.enableProtection()
+                .addRequiredChecks("test-status-check")
+                .requireBranchIsUpToDate()
+                .requireCodeOwnReviews()
+                .dismissStaleReviews()
+                .includeAdmins()
+                .enable();
+
+        RequiredStatusChecks statusChecks = protection.getRequiredStatusChecks();
+        assertNotNull(statusChecks);
+        assertTrue(statusChecks.isRequiresBranchUpToDate());
+        assertTrue(statusChecks.getContexts().contains("test-status-check"));
+        
+        RequiredReviews requiredReviews = protection.getRequiredReviews();
+        assertNotNull(requiredReviews);
+        assertTrue(requiredReviews.isDismissStaleReviews());
+        assertTrue(requiredReviews.isRequireCodeOwnerReviews());
+        
+        EnforceAdmins enforceAdmins = protection.getEnforceAdmins();
+        assertNotNull(enforceAdmins);
+        assertTrue(enforceAdmins.isEnabled());
+    }
+
+    @Test
+    public void testEnableProtectionOnly() throws Exception {
+        branch.enableProtection().enable();
+        assertTrue(repo.getBranch(BRANCH).isProtected());
+    }
+
+    @Test
+    public void testEnableRequireReviewsOnly() throws Exception {
+        GHBranchProtection protection = branch.enableProtection()
+                .requireReviews()
+                .enable();
+        
+       assertNotNull(protection.getRequiredReviews());
+    }
+}

src/test/java/org/kohsuke/github/GHContentIntegrationTest.java

@@ -20,13 +20,6 @@ public class GHContentIntegrationTest extends AbstractGitHubApiTestBase {
         repo = gitHub.getRepository("github-api-test-org/GHContentIntegrationTest").fork();
     }
 
-    @Test
-    public void testBranchProtection() throws Exception {
-        GHBranch b = repo.getBranch("master");
-        b.enableProtection(EnforcementLevel.NON_ADMINS, "foo/bar");
-        b.disableProtection();
-    }
-
     @Test
     public void testGetFileContent() throws Exception {
         GHContent content = repo.getFileContent("ghcontent-ro/a-file-with-content");

src/test/java/org/kohsuke/github/PullRequestTest.java

@@ -7,6 +7,9 @@ import java.io.IOException;
 import java.util.Collection;
 import java.util.List;
 
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.notNullValue;
+
 /**
  * @author Kohsuke Kawaguchi
  */
@@ -26,6 +29,33 @@ public class PullRequestTest extends AbstractGitHubApiTestBase {
         p.comment("Some comment");
     }
 
+    @Test 
+    public void testPullRequestReviews() throws Exception {
+        String name = rnd.next();
+        GHPullRequest p = getRepository().createPullRequest(name, "stable", "master", "## test");
+        GHPullRequestReview draftReview = p.createReview("Some draft review", null,
+                GHPullRequestReviewComment.draft("Some niggle", "changelog.html", 1)
+        );
+        assertThat(draftReview.getState(), is(GHPullRequestReviewState.PENDING));
+        assertThat(draftReview.getBody(), is("Some draft review"));
+        assertThat(draftReview.getCommitId(), notNullValue());
+        List<GHPullRequestReview> reviews = p.listReviews().asList();
+        assertThat(reviews.size(), is(1));
+        GHPullRequestReview review = reviews.get(0);
+        assertThat(review.getState(), is(GHPullRequestReviewState.PENDING));
+        assertThat(review.getBody(), is("Some draft review"));
+        assertThat(review.getCommitId(), notNullValue());
+        review.submit("Some review comment", GHPullRequestReviewState.COMMENTED);
+        List<GHPullRequestReviewComment> comments = review.listReviewComments().asList();
+        assertEquals(1, comments.size());
+        GHPullRequestReviewComment comment = comments.get(0);
+        assertEquals("Some niggle", comment.getBody());
+        review = p.createReview("Some new review", null,
+                GHPullRequestReviewComment.draft("Some niggle", "changelog.html", 1)
+        );
+        review.delete();
+    }
+
     @Test
     public void testPullRequestReviewComments() throws Exception {
         String name = rnd.next();

src/test/java/org/kohsuke/github/RepositoryTest.java

@@ -3,6 +3,7 @@ package org.kohsuke.github;
 import org.junit.Test;
 import org.kohsuke.github.GHRepository.Contributor;
 
+import java.io.FileNotFoundException;
 import java.io.IOException;
 
 /**
@@ -40,6 +41,59 @@ public class RepositoryTest extends AbstractGitHubApiTestBase {
         assertTrue(kohsuke);
     }
 
+    @Test
+    public void getPermission() throws Exception {
+        kohsuke();
+        GHRepository r = gitHub.getRepository("github-api-test-org/test-permission");
+        assertEquals(GHPermissionType.ADMIN, r.getPermission("kohsuke"));
+        assertEquals(GHPermissionType.READ, r.getPermission("dude"));
+        r = gitHub.getOrganization("apache").getRepository("groovy");
+        try {
+            r.getPermission("jglick");
+            fail();
+        } catch (HttpException x) {
+            x.printStackTrace(); // good
+            assertEquals(403, x.getResponseCode());
+        }
+
+        if (false) {
+            // can't easily test this; there's no private repository visible to the test user
+            r = gitHub.getOrganization("cloudbees").getRepository("private-repo-not-writable-by-me");
+            try {
+                r.getPermission("jglick");
+                fail();
+            } catch (FileNotFoundException x) {
+                x.printStackTrace(); // good
+            }
+        }
+    }
+    
+    
+	
+	@Test
+	public void LatestRepositoryExist() {
+		try {
+			// add the repository that have latest release
+			GHRelease release = gitHub.getRepository("kamontat/CheckIDNumber").getLatestRelease();
+			assertEquals("v3.0", release.getTagName());
+		} catch (IOException e) {
+			e.printStackTrace();
+			fail();
+		}
+	}
+	
+	@Test
+	public void LatestRepositoryNotExist() {
+		try {
+			// add the repository that `NOT` have latest release
+			GHRelease release = gitHub.getRepository("kamontat/Java8Example").getLatestRelease();
+			assertNull(release);
+		} catch (IOException e) {
+			e.printStackTrace();
+			fail();
+		}
+	}
+
     private GHRepository getRepository() throws IOException {
         return gitHub.getOrganization("github-api-test-org").getRepository("jenkins");
     }

src/test/resources/org/kohsuke/github/GHEventPayloadTest/label.json

@@ -65,8 +65,7 @@
     "issues_url": "https://api.github.com/repos/baxterandthehackers/public-repo/issues{/number}",
     "pulls_url": "https://api.github.com/repos/baxterandthehackers/public-repo/pulls{/number}",
     "milestones_url": "https://api.github.com/repos/baxterandthehackers/public-repo/milestones{/number}",
-    "notifications_url": "https://api.github.com/repos/baxterandthehackers/public-repo/notifications{?since,all,
-    participating}",
+    "notifications_url": "https://api.github.com/repos/baxterandthehackers/public-repo/notifications{?since,all,participating}",
     "labels_url": "https://api.github.com/repos/baxterandthehackers/public-repo/labels{/name}",
     "releases_url": "https://api.github.com/repos/baxterandthehackers/public-repo/releases{/id}",
     "deployments_url": "https://api.github.com/repos/baxterandthehackers/public-repo/deployments",

src/test/resources/org/kohsuke/github/GHEventPayloadTest/milestone.json

@@ -2,8 +2,7 @@
   "action": "created",
   "milestone": {
     "url": "https://api.github.com/repos/baxterandthehackers/public-repo/milestones/3",
-    "html_url": "https://github.com/baxterandthehackers/public-repo/milestones/Test%20milestone%20creation%20webhook
-    %20from%20command%20line2",
+    "html_url": "https://github.com/baxterandthehackers/public-repo/milestones/Test%20milestone%20creation%20webhook%20from%20command%20line2",
     "labels_url": "https://api.github.com/repos/baxterandthehackers/public-repo/milestones/3/labels",
     "id": 2055681,
     "number": 3,
@@ -96,8 +95,7 @@
     "issues_url": "https://api.github.com/repos/baxterandthehackers/public-repo/issues{/number}",
     "pulls_url": "https://api.github.com/repos/baxterandthehackers/public-repo/pulls{/number}",
     "milestones_url": "https://api.github.com/repos/baxterandthehackers/public-repo/milestones{/number}",
-    "notifications_url": "https://api.github.com/repos/baxterandthehackers/public-repo/notifications{?since,all,
-    participating}",
+    "notifications_url": "https://api.github.com/repos/baxterandthehackers/public-repo/notifications{?since,all,participating}",
     "labels_url": "https://api.github.com/repos/baxterandthehackers/public-repo/labels{/name}",
     "releases_url": "https://api.github.com/repos/baxterandthehackers/public-repo/releases{/id}",
     "deployments_url": "https://api.github.com/repos/baxterandthehackers/public-repo/deployments",