Merge tag 'github-api-1.322' into release/v1.x

github-api-1.322

.github/workflows/maven-build.yml

@@ -86,7 +86,7 @@ jobs:
       run: mvn -B clean install -D enable-ci --file pom.xml "-Dsurefire.argLine=--add-opens java.base/java.net=ALL-UNNAMED"
     - name: Codecov Report
       if: matrix.os == 'ubuntu' && matrix.java == '17'
-      uses: codecov/codecov-action@v4.1.0
+      uses: codecov/codecov-action@v4.4.1
 
   test-java-8:
     name: test Java 8 (no-build)

pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>org.kohsuke</groupId>
   <artifactId>github-api</artifactId>
-  <version>1.321</version>
+  <version>1.322</version>
   <name>GitHub API for Java</name>
   <url>https://github-api.kohsuke.org/</url>
   <description>GitHub API for Java</description>
@@ -44,7 +44,7 @@
     <jacoco.coverage.target.class.method>0.50</jacoco.coverage.target.class.method>
     <!-- For non-ci builds we'd like the build to still complete if jacoco metrics aren't met. -->
     <jacoco.haltOnFailure>false</jacoco.haltOnFailure>
-    <jjwt.suite.version>0.12.3</jjwt.suite.version>
+    <jjwt.suite.version>0.12.5</jjwt.suite.version>
 
     <jacoco.surefire.argLine />
     <surefire.argLine />
@@ -223,7 +223,7 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-javadoc-plugin</artifactId>
-          <version>3.4.1</version>
+          <version>3.6.3</version>
           <configuration>
             <release>8</release>
             <failOnWarnings>true</failOnWarnings>
@@ -350,7 +350,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-jar-plugin</artifactId>
-        <version>3.3.0</version>
+        <version>3.4.1</version>
         <configuration>
           <archive>
             <manifestEntries>
@@ -526,7 +526,7 @@
     <dependency>
       <groupId>org.awaitility</groupId>
       <artifactId>awaitility</artifactId>
-      <version>4.2.0</version>
+      <version>4.2.1</version>
       <scope>test</scope>
     </dependency>
     <dependency>

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

@@ -0,0 +1,69 @@
+package org.kohsuke.github;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.util.Optional;
+import java.util.logging.Logger;
+
+/**
+ * Utility class for helping with operations for enterprise managed resources.
+ *
+ * @author Miguel Esteban Gutiérrez
+ */
+class EnterpriseManagedSupport {
+
+    static final String COULD_NOT_RETRIEVE_ORGANIZATION_EXTERNAL_GROUPS = "Could not retrieve organization external groups";
+    static final String NOT_PART_OF_EXTERNALLY_MANAGED_ENTERPRISE_ERROR = "This organization is not part of externally managed enterprise.";
+    static final String TEAM_CANNOT_BE_EXTERNALLY_MANAGED_ERROR = "This team cannot be externally managed since it has explicit members.";
+
+    private static final Logger LOGGER = Logger.getLogger(EnterpriseManagedSupport.class.getName());
+
+    private final GHOrganization organization;
+
+    private EnterpriseManagedSupport(GHOrganization organization) {
+        this.organization = organization;
+    }
+
+    Optional<GHIOException> filterException(final HttpException he, final String scenario) {
+        if (he.getResponseCode() == 400) {
+            final String responseMessage = he.getMessage();
+            try {
+                final GHError error = GitHubClient.getMappingObjectReader(this.organization.root())
+                        .forType(GHError.class)
+                        .readValue(responseMessage);
+                if (NOT_PART_OF_EXTERNALLY_MANAGED_ENTERPRISE_ERROR.equals(error.getMessage())) {
+                    return Optional.of(new GHNotExternallyManagedEnterpriseException(scenario, error, he));
+                } else if (TEAM_CANNOT_BE_EXTERNALLY_MANAGED_ERROR.equals(error.getMessage())) {
+                    return Optional.of(new GHTeamCannotBeExternallyManagedException(scenario, error, he));
+                }
+            } catch (final JsonProcessingException e) {
+                // We can ignore it
+                LOGGER.warning(() -> logUnexpectedFailure(e, responseMessage));
+            }
+        }
+        return Optional.empty();
+    }
+
+    Optional<GHException> filterException(final GHException e) {
+        if (e.getCause() instanceof HttpException) {
+            final HttpException he = (HttpException) e.getCause();
+            return filterException(he, COULD_NOT_RETRIEVE_ORGANIZATION_EXTERNAL_GROUPS)
+                    .map(translated -> new GHException(COULD_NOT_RETRIEVE_ORGANIZATION_EXTERNAL_GROUPS, translated));
+        }
+        return Optional.empty();
+    }
+
+    static EnterpriseManagedSupport forOrganization(final GHOrganization org) {
+        return new EnterpriseManagedSupport(org);
+    }
+
+    private static String logUnexpectedFailure(final JsonProcessingException exception, final String payload) {
+        final StringWriter sw = new StringWriter();
+        final PrintWriter pw = new PrintWriter(sw);
+        exception.printStackTrace(pw);
+        return String.format("Could not parse GitHub error response: '%s'. Full stacktrace follows:%n%s", payload, sw);
+    }
+
+}

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

@@ -1,5 +1,6 @@
 package org.kohsuke.github;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 
@@ -221,6 +222,55 @@ public boolean isEnabled() {
         }
     }
 
+    /**
+     * The type Check.
+     */
+    public static class Check {
+        private String context;
+
+        @JsonInclude(JsonInclude.Include.NON_NULL)
+        private Integer appId;
+
+        /**
+         * no-arg constructor for the serializer
+         */
+        public Check() {
+        }
+
+        /**
+         * Regular constructor for use in user business logic
+         *
+         * @param context
+         *            the context string of the check
+         * @param appId
+         *            the application ID the check is supposed to come from. Pass "-1" to explicitly allow any app to
+         *            set the status. Pass "null" to automatically select the GitHub App that has recently provided this
+         *            check.
+         */
+        public Check(String context, Integer appId) {
+            this.context = context;
+            this.appId = appId;
+        }
+
+        /**
+         * The context string of the check
+         *
+         * @return the string
+         */
+        public String getContext() {
+            return context;
+        }
+
+        /**
+         * The application ID the check is supposed to come from. The value "-1" indicates "any source".
+         *
+         * @return the integer
+         */
+        public Integer getAppId() {
+            return appId;
+        }
+    }
+
     /**
      * The type AllowForcePushes.
      */
@@ -462,6 +512,9 @@ public static class RequiredStatusChecks {
         @JsonProperty
         private Collection<String> contexts;
 
+        @JsonProperty
+        private Collection<Check> checks;
+
         @JsonProperty
         private boolean strict;
 
@@ -477,6 +530,15 @@ public Collection<String> getContexts() {
             return Collections.unmodifiableCollection(contexts);
         }
 
+        /**
+         * Gets checks.
+         *
+         * @return the checks
+         */
+        public Collection<Check> getChecks() {
+            return Collections.unmodifiableCollection(checks);
+        }
+
         /**
          * Gets url.
          *

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

@@ -11,6 +11,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 import static org.kohsuke.github.internal.Previews.LUKE_CAGE;
 
@@ -50,8 +51,23 @@ public class GHBranchProtectionBuilder {
      *            the checks
      * @return the gh branch protection builder
      */
+    public GHBranchProtectionBuilder addRequiredStatusChecks(Collection<GHBranchProtection.Check> checks) {
+        getStatusChecks().checks.addAll(checks);
+        return this;
+    }
+
+    /**
+     * Add required checks gh branch protection builder.
+     *
+     * @param checks
+     *            the checks
+     * @return the gh branch protection builder
+     */
+    @Deprecated
     public GHBranchProtectionBuilder addRequiredChecks(Collection<String> checks) {
-        getStatusChecks().contexts.addAll(checks);
+        getStatusChecks().checks.addAll(checks.stream()
+                .map(context -> new GHBranchProtection.Check(context, null))
+                .collect(Collectors.toList()));
         return this;
     }
 
@@ -62,11 +78,24 @@ public GHBranchProtectionBuilder addRequiredChecks(Collection<String> checks) {
      *            the checks
      * @return the gh branch protection builder
      */
+    @Deprecated
     public GHBranchProtectionBuilder addRequiredChecks(String... checks) {
         addRequiredChecks(Arrays.asList(checks));
         return this;
     }
 
+    /**
+     * Add required checks gh branch protection builder.
+     *
+     * @param checks
+     *            the checks
+     * @return the gh branch protection builder
+     */
+    public GHBranchProtectionBuilder addRequiredChecks(GHBranchProtection.Check... checks) {
+        addRequiredStatusChecks(Arrays.asList(checks));
+        return this;
+    }
+
     /**
      * Allow deletion of the protected branch.
      *
@@ -547,7 +576,7 @@ private static class Restrictions {
     }
 
     private static class StatusChecks {
-        final List<String> contexts = new ArrayList<String>();
+        final List<GHBranchProtection.Check> checks = new ArrayList<>();
         boolean strict;
     }
 }

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

@@ -0,0 +1,44 @@
+package org.kohsuke.github;
+
+/**
+ * Failure related to Enterprise Managed Users operations.
+ *
+ * @author Miguel Esteban Gutiérrez
+ */
+public class GHEnterpriseManagedUsersException extends GHIOException {
+
+    /**
+     * The serial version UID of the exception.
+     */
+    private static final long serialVersionUID = 1980051901L;
+
+    /**
+     * The error that caused the exception.
+     */
+    private final GHError error;
+
+    /**
+     * Instantiates a new exception.
+     *
+     * @param message
+     *            the message
+     * @param error
+     *            the error that caused the exception
+     * @param cause
+     *            the cause
+     */
+    public GHEnterpriseManagedUsersException(final String message, final GHError error, final Throwable cause) {
+        super(message, cause);
+        this.error = error;
+    }
+
+    /**
+     * Get the error that caused the exception.
+     *
+     * @return the error
+     */
+    public GHError getError() {
+        return error;
+    }
+
+}

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

@@ -0,0 +1,52 @@
+package org.kohsuke.github;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+import java.io.Serializable;
+import java.net.URL;
+
+/**
+ * Represents an error from GitHub.
+ *
+ * @author Miguel Esteban Gutiérrez
+ */
+public class GHError implements Serializable {
+
+    /**
+     * The serial version UID of the error
+     */
+    private static final long serialVersionUID = 2008071901;
+
+    /**
+     * The error message.
+     */
+    @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Field comes from JSON deserialization")
+    private String message;
+
+    /**
+     * The URL to the documentation for the error.
+     */
+    @JsonProperty("documentation_url")
+    @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Field comes from JSON deserialization")
+    private String documentation;
+
+    /**
+     * Get the error message.
+     *
+     * @return the message
+     */
+    public String getMessage() {
+        return message;
+    }
+
+    /**
+     * Get the URL to the documentation for the error.
+     *
+     * @return the url
+     */
+    public URL getDocumentationUrl() {
+        return GitHubClient.parseURL(documentation);
+    }
+
+}

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

@@ -1445,6 +1445,16 @@ public void setRelease(GHRelease release) {
      * @see <a href="https://docs.github.com/en/rest/reference/repos">Repositories</a>
      */
     public static class Repository extends GHEventPayload {
+        private GHRepositoryChanges changes;
+
+        /**
+         * Get changes.
+         *
+         * @return GHRepositoryChanges
+         */
+        public GHRepositoryChanges getChanges() {
+            return changes;
+        }
 
     }