Merge pull request #3 from artstorm/feature/git-trailers

Add git.getTrailerValue() function

Author: artstorm

README.md

@@ -6,27 +6,66 @@
 
 A Jenkins shared library with a collection of pipeline steps and functionality useful when setting up a Jenkins CI pipeline for Unity projects. In addition to Unity specific functionality, there is also a selection of more generic functions and steps that have proven useful when setting up continuous integration for game dev projects.
 
+## Available Functions
+
+### Unity Specific
+
+| Function                                                                       | Summary                                                           |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| [unityBuildNumber](#unity-build-number)                                        | Get the build number set for the Standalone build in Unity.       |
+| [unityCodeCoverageReport](#unity-code-coverage-report)                         | Runs Unity's Code Coverage reporter.                              |
+| [unityCodeCoverageReportSummary](#unity-code-coverage-report-summary)          | Parses Summary.xml from the Unity generated code coverage report. |
+| [unityPublishCodeCoverageHTMLReport](#unity-publish-code-coverage-html-report) | Publishes the Unity Code Coverage Report to the job page.         |
+| [unityTestRunner](#unity-test-runner)                                          | Uses Unity's Test Runner to execute the test suite.               |
+| [unityTestRunnerReport](#unity-test-runner-report)                             | Create a report from NUnit tests.                                 |
+| [tests.summary](#tests)                                                        | Get Junit test result summary.                                    |
+
+### Generic
+
+| Function                                                  | Summary                                                                |
+| --------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [getBuildType](#get-build-type)                           | Retrieves the build type for the current running build.                |
+| [setJobDisplayName](#set-job-display-name)                | Sets the display name based on the build type.                         |
+| [git.branchName](#git-branch-name)                        | Get the current branch name.                                           |
+| [git.commitSha](#git-commit-sha)                          | Get the full git commit sha for current commit.                        |
+| [git.commitShaShort](#git-commit-sha-short)               | Get the short 7 character git commit sha for current commit.           |
+| [git.getTrailerValue](#git-trailer-value)                 | Get the trailer value for the specified token.                         |
+| [github.pullRequestComment](#github-pull-request-comment) | Creates or updates the Jenkins bot issue comment for the pull request. |
+| [github.ownerRepo](#github-owner-repo)                    | Get the `owner/repo` part from the project's git url.                  |
+| [github.pullRequest](#github-pull-request)                | Returns the pull request the current commit belongs to.                |
+| [github.issueComments](#github-issue-comments)            | Retrieves all comments for an issue/pull request.                      |
+| [github.createIssueComment](#github-create-issue-comment) | Create issue comment.                                                  |
+| [github.updateIssueComment](#github-update-issue-comment) | Update issue comment.                                                  |
+| [github.createCheckRun](#github-create-check-run)         | Create a check run.                                                    |
+| [github.updateCheckRun](#github-update-check-run)         | Update a check run.                                                    |
+
 ## Installation
+
 Read the [Extending with Shared Libraries > Using Libraries](https://www.jenkins.io/doc/book/pipeline/shared-libraries/#using-libraries) section in Jenkins User Handbook for full instruction how to add a shared library to a Jenkins instance and how to access the functionality from a `Jenkinsfile`.
 
 When using the library in a Jenkinsfile, use a version specifier, to avoid surprises if future updates of the library introduces breaking changes.
 
 ```groovy
-@Library('shared-library@v1.0.3') _
+@Library('shared-library@v1.0.4') _
 ```
 
 ### Pipeline Utility Steps
+
 Several functions in this library uses functions from the Jenkins plugin [Pipeline Utility Steps](https://plugins.jenkins.io/pipeline-utility-steps/). Make sure this plugin is installed in the Jenkins instance using this shared library.
 
 ### GitHub App
-For the GitHub specific steps a GitHub app must be registered to obtain the access token for Jenkins to communicate with the GitHub API. It also requires the Jenkins plugins 
+
+For the GitHub specific steps a GitHub app must be registered to obtain the access token for Jenkins to communicate with the GitHub API. It also requires the Jenkins plugins
 
 ## Pipeline Steps and Functions
+
 An overview of the pipeline steps and functionality this shared library exposes.
 
 ### Unity Specific
+
 #### Unity Build Number
-This function parses Unity's Project Settings and returns the build number that has been set 
+
+This function parses Unity's Project Settings and returns the build number that has been set
 for the Standalone build in Unity's `Project Settings > Player > Build`.
 
 ```groovy
@@ -36,6 +75,7 @@ steps {
 ```
 
 #### Unity Code Coverage Report
+
 Runs Unity's Code Coverage reporter. This assumes the Unity project has the Code Coverage package installed.
 
 The reporter takes two parameters, `unityCodeCoverageReport(assemblyFilters, pathFilters)`.
@@ -48,23 +88,26 @@ post {
     }
 }
 ```
+
 #### Unity Code Coverage Report Summary
+
 Parses `Summary.xml` from the Unity generated code coverage report and returns the summary as an object with the summary items as properties. This can then be posted to Discord, Slack, a time series database, or any other destination.
 
 Available properties:
 
-- coveredLines
-- uncoveredLines
-- coverableLines
-- totalLines
-- lineCoverage
+-   coveredLines
+-   uncoveredLines
+-   coverableLines
+-   totalLines
+-   lineCoverage
 
 ```groovy
 def codeCoverage = unityCodeCoverageReportSummary()
 echo  "${codeCoverage.lineCoverage}"
 ```
 
 #### Unity Publish Code Coverage HTML Report
+
 Publishes the Unity Code Coverage Report so it's available from the job page.
 
 ```groovy
@@ -76,6 +119,7 @@ post {
 ```
 
 #### Unity Test Runner
+
 Uses Unity's Test Runner to execute the test suite.
 
 ```groovy
@@ -85,6 +129,7 @@ steps {
 ```
 
 #### Unity Test Runner Report
+
 Creates a merged report from Unitys PlayMode and EditMode test files.
 
 ```groovy
@@ -96,14 +141,15 @@ post {
 ```
 
 #### tests
+
 Parses the results from the Unity test runner and returns the summary as an object. This can then be posted to Discord, Slack, a time series database, or any other destination.
 
 Available properties:
 
-- total
-- failed
-- skipped
-- passed
+-   total
+-   failed
+-   skipped
+-   passed
 
 ```groovy
 def testSummary = tests.summary()
@@ -113,29 +159,32 @@ echo  "${testSummary.passed}"
 ### Common
 
 #### Get Build Type
-Retrieves the build type for the current running build based on branch name prefixes. This is useful to rely on branch names to determine the build logic. 
 
-- internal: `/feature/*`
-- testflight: `/testflight/*`
-- release: `/release/*`
-- standard: `*` 
+Retrieves the build type for the current running build based on branch name prefixes. This is useful to rely on branch names to determine the build logic.
+
+-   internal: `/feature/*`
+-   testflight: `/testflight/*`
+-   release: `/release/*`
+-   standard: `*`
 
 ```groovy
 steps {
-    echo "Build type: ${git.getBuildType()}"
+    echo "Build type: ${getBuildType()}"
 }
 ```
 
-
 #### Set Job Display Name
+
 Sets name for the running job based on git branch name.
+
 ```groovy
 steps {
     setJobDisplayName()
 }
 ```
 
 #### Git Branch Name
+
 Get the current branch name.
 
 ```groovy
@@ -145,6 +194,7 @@ steps {
 ```
 
 #### Git Commit SHA
+
 Get the full git commit sha for current commit.
 
 ```groovy
@@ -154,6 +204,7 @@ steps {
 ```
 
 #### Git Commit SHA Short
+
 Get the short 7 character git commit sha for current commit.
 
 ```groovy
@@ -162,7 +213,18 @@ steps {
 }
 ```
 
+#### Git Trailer Value
+
+Get the [trailer](https://git-scm.com/docs/git-interpret-trailers) value for the specified token for the current commit.
+
+```groovy
+steps {
+    echo "Git commit message trailer value : ${git.getTrailerValue('some-token')}"
+}
+```
+
 #### GitHub Pull Request Comment
+
 Creates or updates the Jenkins bot issue comment for the pull request.
 
 This can be used to have a comment in the PR that Jenkins updates with current information about the build.
@@ -173,54 +235,60 @@ steps {
 }
 ```
 
-
 #### GitHub Owner Repo
+
 Get the <owner/repo> part from the project's git url.
 
 ```groovy
 def owner = github.ownerRepo()
 ```
 
 #### GitHub Pull Request
+
 Returns the pull request the current commit belongs to.
 
 ```groovy
 def pr = github.pullRequest()
 ```
 
 #### GitHub Issue Comments
+
 Retrieves all comments for an issue/pull request.
 
 ```groovy
 def comment = github.issueComments(42)
 ```
 
 #### GitHub Create Issue Comment
+
 Create issue comment.
 
 ```groovy
 github.createIssueComment(42, "some comment")
 ```
 
-
 #### GitHub Update Issue Comment
+
 Update issue comment.
 
 ```groovy
-github.createIssueComment(42, "some updated comment")
+github.updateIssueComment(42, "some updated comment")
 ```
 
 #### GitHub Create Check Run
+
 Create a check run.
 
 Start a check run for a specific build build.
+
 ```groovy
 steps {
     checkRunIosId = github.createCheckRun("build_ios", "queued")
 }
 ```
 
 #### GitHub Update Check Run
+
 Update a check run.
 
 ```groovy
@@ -236,4 +304,34 @@ success {
         github.updateCheckRun(checkRunIosId, '', 'success')
     }
 }
-```
+```
+
+## Development
+
+Gradle is used to test the pipeline during development.
+
+### Running Tests
+
+The test suite is executed with:
+
+```sh
+./gradlew test
+```
+
+Then gradle is executed for the first time in a session a daemon is started. Manage the daemon with these commands.
+
+```sh
+## See running daemons
+gradle --status
+
+## Stop running daemons
+gradle --stop
+```
+
+### macOS
+
+Gradle needs Java runtime, and the version of Gradle used in this project uses Java 17. Install Java 17 with Homebrew and then set `JAVA_HOME` in the terminal, for the session, in the terminal.
+
+```
+export JAVA_HOME=/usr/local/opt/openjdk@17
+```

vars/git.groovy

@@ -33,3 +33,14 @@ def branchName() {
 def commitShaShort() {
   return sh(returnStdout: true, script: "git rev-parse --short HEAD").trim();
 }
+
+/**
+ *  Get the trailer value for the specified token for the current commit message.
+ *
+ * Resources:
+ * - https://git-scm.com/docs/git-interpret-trailers
+ * - https://stackoverflow.com/q/69532088/1152087
+ */
+def getTrailerValue(String token) {
+  return sh(returnStdout: true, script: "git log -1 --pretty='%(trailers:key=${token},valueonly)'")
+}

vars/git.txt

@@ -1,16 +1,16 @@
 <dl>
-  <dt><code>git.branchName()</code></dt>
-  <dd>
-  Get the current branch name.
-  </dd>
+    <dt><code>git.branchName()</code></dt>
+    <dd>Get the current branch name.</dd>
 
-  <dt><code>git.commitSha()</code></dt>
-  <dd>
-  Get the full git commit sha for current commit.
-  </dd>
+    <dt><code>git.commitSha()</code></dt>
+    <dd>Get the full git commit sha for current commit.</dd>
 
-  <dt><code>git.commitShaShort()</code></dt>
-  <dd>
-  Get the short 7 character git commit sha for current commit.
-  </dd>
-</dl>
+    <dt><code>git.commitShaShort()</code></dt>
+    <dd>Get the short 7 character git commit sha for current commit.</dd>
+
+    <dt><code>git.getTrailerValue(String token)</code></dt>
+    <dd>
+        Get the trailer value for the specified token for the current commit
+        message.
+    </dd>
+</dl>