Read ref from GITHUB_HEAD_REF env variable if it's present (#776)

* Read ref from GITHUB_HEAD_REF env variable if it's present

* Clear Github Actions env variables in tests

* Implement annotation-driven extension @WithEnvironment and use it in test for GITHUB_HEAD_REF

* Extract ClearGithubEnvVariablesExtension

* Refactor WithEnvironmentExtension

* Add JavaDoc

* Support other Github event types

* Go back to reading only GITHUB_HEAD_REF, provide documentation and JavaDocs

Author: radoslaw-panuszewski

docs/configuration/version.md

@@ -297,6 +297,8 @@ collection type used (default for `[:]` is LinkedHashMap).
 
 #### versionWithBranch [default]
 
+This is the default version creator since version 1.18.0 of the plugin.
+
     scmVersion {
         versionCreator('versionWithBranch')
     }
@@ -307,7 +309,13 @@ This version creator appends branch name to version unless you are on
     decorate(version: '0.1.0', branch: 'master') == 0.1.0
     decorate(version: '0.1.0', branch: 'my-special-branch') == 0.1.0-my-special-branch
 
-This is the default version creator since version 1.18.0 of the plugin. 
+If your Gradle build is executed within workflow on GitHub Actions and that workflow is triggered by either
+`pull_request` or `pull_request_target` event, GitHub will not check out the source branch of the pull request but
+a custom reference `refs/pull/<pr_number>/merge` (known as "merge branch"). Consequently, the repository will be in
+detached-HEAD state.
+
+In that case, the branch name will be taken from `GITHUB_HEAD_REF` environment variable
+[provided by GitHub](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables).
 
 #### simple
 

src/main/java/pl/allegro/tech/build/axion/release/infrastructure/git/GitRepository.java

@@ -1,55 +1,26 @@
 package pl.allegro.tech.build.axion.release.infrastructure.git;
 
-import org.eclipse.jgit.api.AddCommand;
-import org.eclipse.jgit.api.FetchCommand;
-import org.eclipse.jgit.api.Git;
-import org.eclipse.jgit.api.LogCommand;
-import org.eclipse.jgit.api.PushCommand;
-import org.eclipse.jgit.api.Status;
+import org.eclipse.jgit.api.*;
 import org.eclipse.jgit.api.errors.GitAPIException;
 import org.eclipse.jgit.api.errors.NoHeadException;
 import org.eclipse.jgit.diff.DiffFormatter;
 import org.eclipse.jgit.errors.RepositoryNotFoundException;
-import org.eclipse.jgit.lib.AnyObjectId;
-import org.eclipse.jgit.lib.BranchTrackingStatus;
-import org.eclipse.jgit.lib.Config;
-import org.eclipse.jgit.lib.Constants;
-import org.eclipse.jgit.lib.ObjectId;
-import org.eclipse.jgit.lib.Ref;
-import org.eclipse.jgit.lib.Repository;
-import org.eclipse.jgit.lib.StoredConfig;
+import org.eclipse.jgit.lib.*;
 import org.eclipse.jgit.revwalk.RevCommit;
 import org.eclipse.jgit.revwalk.RevSort;
 import org.eclipse.jgit.revwalk.RevWalk;
-import org.eclipse.jgit.transport.PushResult;
-import org.eclipse.jgit.transport.RemoteConfig;
-import org.eclipse.jgit.transport.RemoteRefUpdate;
-import org.eclipse.jgit.transport.TagOpt;
-import org.eclipse.jgit.transport.URIish;
+import org.eclipse.jgit.transport.*;
 import org.eclipse.jgit.treewalk.filter.PathFilter;
 import org.eclipse.jgit.util.SystemReader;
 import org.eclipse.jgit.util.io.DisabledOutputStream;
 import org.gradle.api.logging.Logger;
 import org.gradle.api.logging.Logging;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmException;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmIdentity;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmPosition;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmProperties;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmPushOptions;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmPushResult;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmRepository;
-import pl.allegro.tech.build.axion.release.domain.scm.ScmRepositoryUnavailableException;
-import pl.allegro.tech.build.axion.release.domain.scm.TagsOnCommit;
+import pl.allegro.tech.build.axion.release.domain.scm.*;
 
 import java.io.File;
 import java.io.IOException;
 import java.net.URISyntaxException;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.Optional;
+import java.util.*;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import java.util.stream.StreamSupport;
@@ -333,37 +304,72 @@ private void assertPathExists(String path) {
     }
 
     public ScmPosition currentPosition() {
+        String revision = getRevision();
+        String branchName = branchName();
+        boolean isClean = !checkUncommittedChanges();
+        return new ScmPosition(revision, branchName, isClean);
+    }
+
+    private String getRevision() {
         try {
             String revision = "";
             if (hasCommits()) {
                 ObjectId head = head();
                 revision = head.name();
             }
-
-            boolean isClean = !checkUncommittedChanges();
-
-            String branchName = branchName();
-            return new ScmPosition(revision, branchName, isClean);
+            return revision;
         } catch (IOException e) {
             throw new ScmException(e);
         }
     }
 
+    private String branchName() {
+        return branchNameFromGithubEnvVariable().orElseGet(this::branchNameFromGit);
+    }
+
     /**
-     * @return branch name or 'HEAD' when in detached state, unless it is overridden by 'overriddenBranchName'
+     * <p>If executed within workflow on GitHub Actions and that workflow is triggered by pull_request (or pull_request_target)
+     * event, GitHub will not check out the source branch of the PR, but some custom ref: 'refs/pull/<pr_number>/merge'
+     * (they call it a "merge branch"). It effectively means that repository is in detached-HEAD state and axion-release
+     * is not able to get the branch name from HEAD ref.</p>
+     *
+     * <p>For pull_request and pull_request_target events, GitHub sets a special environment variable GITHUB_HEAD_REF.
+     * It contains the head ref of source branch of the PR which triggered the workflow. This variable is not set
+     * for other event types.</p>
+     *
+     * <p>If the build is not executed on GitHub Actions, this method will always return Optional.empty.</p>
+     *
+     *  @return source branch of the PR which triggered GitHub Actions workflow
      */
-    private String branchName() throws IOException {
-        // this returns HEAD as branch name when in detached state
-        Optional<Ref> ref = Optional.ofNullable(jgitRepository.getRepository().exactRef(Constants.HEAD));
-        String branchName = ref.map(r -> r.getTarget().getName())
-            .map(Repository::shortenRefName)
-            .orElse(null);
-
-        if ("HEAD".equals(branchName) && properties.getOverriddenBranchName() != null && !properties.getOverriddenBranchName().isEmpty()) {
-            branchName = Repository.shortenRefName(properties.getOverriddenBranchName());
+    private Optional<String> branchNameFromGithubEnvVariable() {
+        if (env("GITHUB_ACTIONS").isPresent()) {
+            return env("GITHUB_HEAD_REF");
         }
+        return Optional.empty();
+    }
+
+    private Optional<String> env(String name) {
+        return Optional.ofNullable(System.getenv(name));
+    }
 
-        return branchName;
+    /**
+     * @return branch name or 'HEAD' when in detached state, unless it is overridden by 'overriddenBranchName'
+     */
+    private String branchNameFromGit() {
+        try {
+            // this returns HEAD as branch name when in detached state
+            Optional<Ref> ref = Optional.ofNullable(jgitRepository.getRepository().exactRef(Constants.HEAD));
+            String branchName = ref.map(r -> r.getTarget().getName())
+                .map(Repository::shortenRefName)
+                .orElse(null);
+
+            if ("HEAD".equals(branchName) && properties.getOverriddenBranchName() != null && !properties.getOverriddenBranchName().isEmpty()) {
+                branchName = Repository.shortenRefName(properties.getOverriddenBranchName());
+            }
+            return branchName;
+        } catch (IOException e) {
+            throw new ScmException(e);
+        }
     }
 
     @Override

src/test/groovy/pl/allegro/tech/build/axion/release/infrastructure/git/GitRepositoryTest.groovy

@@ -9,16 +9,23 @@ import org.eclipse.jgit.lib.Constants
 import org.eclipse.jgit.transport.RemoteConfig
 import org.eclipse.jgit.transport.URIish
 import org.gradle.testfixtures.ProjectBuilder
-import pl.allegro.tech.build.axion.release.domain.scm.*
+import pl.allegro.tech.build.axion.release.util.WithEnvironment
+import pl.allegro.tech.build.axion.release.domain.scm.ScmException
+import pl.allegro.tech.build.axion.release.domain.scm.ScmIdentity
+import pl.allegro.tech.build.axion.release.domain.scm.ScmPosition
+import pl.allegro.tech.build.axion.release.domain.scm.ScmProperties
+import pl.allegro.tech.build.axion.release.domain.scm.ScmPushOptions
+import pl.allegro.tech.build.axion.release.domain.scm.ScmRepositoryUnavailableException
+import pl.allegro.tech.build.axion.release.domain.scm.TagsOnCommit
 import spock.lang.Specification
 
 import java.nio.file.Files
 import java.nio.file.Path
 import java.util.regex.Pattern
 
 import static java.util.regex.Pattern.compile
-import static pl.allegro.tech.build.axion.release.TagPrefixConf.fullPrefix
 import static pl.allegro.tech.build.axion.release.TagPrefixConf.defaultPrefix
+import static pl.allegro.tech.build.axion.release.TagPrefixConf.fullPrefix
 import static pl.allegro.tech.build.axion.release.domain.scm.ScmPropertiesBuilder.scmProperties
 
 class GitRepositoryTest extends Specification {
@@ -622,11 +629,36 @@ class GitRepositoryTest extends Specification {
         position.revision == headSubDirAChanged
     }
 
+    @WithEnvironment([
+        'GITHUB_ACTIONS=true',
+        'GITHUB_EVENT_NAME=pull_request',
+        'GITHUB_HEAD_REF=pr-source-branch'
+    ])
+    def "should get branch name on Github Actions if pull_request triggered the workflow"() {
+        when:
+        ScmPosition position = repository.currentPosition()
+
+        then:
+        position.branch == 'pr-source-branch'
+    }
+
+    @WithEnvironment([
+        'GITHUB_ACTIONS=true',
+        'GITHUB_EVENT_NAME=pull_request_target',
+        'GITHUB_HEAD_REF=pr-source-branch'
+    ])
+    def "should get branch name on Github Actions if pull_request_target triggered the workflow"() {
+        when:
+            ScmPosition position = repository.currentPosition()
+
+        then:
+            position.branch == 'pr-source-branch'
+    }
+
     private void commitFile(String subDir, String fileName) {
         String fileInA = "${subDir}/${fileName}"
         new File(repositoryDir, subDir).mkdirs()
         new File(repositoryDir, fileInA).createNewFile()
         repository.commit([fileInA], "Add file ${fileName} in ${subDir}")
     }
-
 }

src/test/groovy/pl/allegro/tech/build/axion/release/util/ClearGithubEnvVariablesExtension.groovy

@@ -0,0 +1,16 @@
+package pl.allegro.tech.build.axion.release.util
+
+import org.spockframework.runtime.extension.IGlobalExtension
+
+import static java.util.stream.Collectors.toList
+
+class ClearGithubEnvVariablesExtension implements IGlobalExtension {
+
+    @Override
+    void start() {
+        def keysToRemove = TestEnvironment.getEnvVariableNames().stream()
+            .filter { variableName -> variableName.startsWith("GITHUB_") }
+            .collect(toList())
+        keysToRemove.forEach(TestEnvironment::unsetEnvVariable)
+    }
+}

src/test/groovy/pl/allegro/tech/build/axion/release/util/TestEnvironment.groovy

@@ -0,0 +1,35 @@
+package pl.allegro.tech.build.axion.release.util
+
+/**
+ * <p>Helper class for manipulating environment variables.</p>
+ *
+ * Credits to Kotest's <a href="https://github.com/kotest/kotest/blob/master/kotest-extensions/src/jvmMain/kotlin/io/kotest/extensions/system/SystemEnvironmentExtensions.kt#L26">withEnvironment</a>
+ */
+class TestEnvironment {
+
+    private static Map<String, String> MUTABLE_ENV_MAP
+
+    static  {
+        extractMutableMapFromSystemEnv()
+    }
+
+    private static void extractMutableMapFromSystemEnv() {
+        def envMap = System.getenv()
+        def envMapClass = envMap.getClass()
+        def internalMapField = envMapClass.getDeclaredField("m")
+        internalMapField.setAccessible(true)
+        MUTABLE_ENV_MAP = (Map<String, String>) internalMapField.get(envMap)
+    }
+
+    static void setEnvVariable(String name, String value) {
+        MUTABLE_ENV_MAP.put(name, value)
+    }
+
+    static void unsetEnvVariable(String name) {
+        MUTABLE_ENV_MAP.remove(name)
+    }
+
+    static Set<String> getEnvVariableNames() {
+        return MUTABLE_ENV_MAP.keySet()
+    }
+}

src/test/groovy/pl/allegro/tech/build/axion/release/util/WithEnvironment.groovy

@@ -0,0 +1,17 @@
+package pl.allegro.tech.build.axion.release.util
+
+
+import org.spockframework.runtime.extension.ExtensionAnnotation
+
+import java.lang.annotation.ElementType
+import java.lang.annotation.Retention
+import java.lang.annotation.RetentionPolicy
+import java.lang.annotation.Target
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ExtensionAnnotation(WithEnvironmentExtension.class)
+@interface WithEnvironment {
+
+    String[] value()
+}

src/test/groovy/pl/allegro/tech/build/axion/release/util/WithEnvironmentExtension.groovy

@@ -0,0 +1,26 @@
+package pl.allegro.tech.build.axion.release.util
+
+import org.spockframework.runtime.extension.IAnnotationDrivenExtension
+import org.spockframework.runtime.model.FeatureInfo
+import org.spockframework.util.Pair
+
+import static java.util.stream.Collectors.toList
+import static TestEnvironment.setEnvVariable
+import static TestEnvironment.unsetEnvVariable
+
+class WithEnvironmentExtension implements IAnnotationDrivenExtension<WithEnvironment> {
+
+    @Override
+    void visitFeatureAnnotation(WithEnvironment annotation, FeatureInfo feature) {
+        feature.getFeatureMethod().addInterceptor { invocation ->
+            List<Pair<String, String>> envVarDefinitions = annotation.value().toList().stream()
+                .map { it.split("=") }
+                .map { Pair.of(it[0], it[1]) }
+                .collect(toList())
+
+            envVarDefinitions.forEach { setEnvVariable(it.first(), it.second()) }
+            invocation.proceed()
+            envVarDefinitions.forEach { unsetEnvVariable(it.first()) }
+        }
+    }
+}

src/test/resources/META-INF/services/org.spockframework.runtime.extension.IGlobalExtension

@@ -0,0 +1 @@
+pl.allegro.tech.build.axion.release.util.ClearGithubEnvVariablesExtension