{"id":15606446,"url":"https://github.com/artstorm/jenkins-shared-library-unity","last_synced_at":"2025-04-28T10:12:49.873Z","repository":{"id":142364508,"uuid":"408252567","full_name":"artstorm/jenkins-shared-library-unity","owner":"artstorm","description":"A Jenkins Shared Library with a collection of functions for Unity projects.","archived":false,"fork":false,"pushed_at":"2023-03-10T14:35:16.000Z","size":114,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-25T00:28:03.639Z","etag":null,"topics":["ci","continuous-integration","game-ci","game-development","gamedev","jenkins","jenkins-pipeline","jenkins-shared-library","unity"],"latest_commit_sha":null,"homepage":"","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artstorm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-19T22:40:34.000Z","updated_at":"2024-08-12T11:43:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"7efc1107-1faa-4396-9ff2-d19020a31ff0","html_url":"https://github.com/artstorm/jenkins-shared-library-unity","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artstorm%2Fjenkins-shared-library-unity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artstorm%2Fjenkins-shared-library-unity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artstorm%2Fjenkins-shared-library-unity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artstorm%2Fjenkins-shared-library-unity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artstorm","download_url":"https://codeload.github.com/artstorm/jenkins-shared-library-unity/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242450892,"owners_count":20130274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","continuous-integration","game-ci","game-development","gamedev","jenkins","jenkins-pipeline","jenkins-shared-library","unity"],"created_at":"2024-10-03T04:40:23.238Z","updated_at":"2025-03-07T19:31:17.110Z","avatar_url":"https://github.com/artstorm.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jenkins Shared Library for Unity\n\n[![Test Suite](https://github.com/artstorm/jenkins-shared-library-unity/actions/workflows/tests.yml/badge.svg)](https://github.com/artstorm/jenkins-shared-library-unity/actions)\n[![Mastodon: @johansteen](https://img.shields.io/badge/mastodon-@johansteen-blue.svg?logo=mastodon\u0026logoColor=ffffff\u0026labelColor=383f47)](https://mastodon.gamedev.place/@johansteen)\n[![Twitter: @artstorm](https://img.shields.io/badge/twitter-@artstorm-blue.svg?logo=twitter\u0026logoColor=ffffff\u0026labelColor=383f47)](https://twitter.com/artstorm)\n[![Discord: Bitbebop](https://img.shields.io/badge/chat-discord-blue?logo=discord\u0026logoColor=ffffff\u0026labelColor=383f47)](https://discord.gg/WJn7w5WaU9)\n\nA 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.\n\n## Available Functions\n\n### Unity Specific\n\n| Function                                                                       | Summary                                                           |\n| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |\n| [unityBuildNumber](#unity-build-number)                                        | Get the build number set for the Standalone build in Unity.       |\n| [unityCodeCoverageReport](#unity-code-coverage-report)                         | Runs Unity's Code Coverage reporter.                              |\n| [unityCodeCoverageReportSummary](#unity-code-coverage-report-summary)          | Parses Summary.xml from the Unity generated code coverage report. |\n| [unityPublishCodeCoverageHTMLReport](#unity-publish-code-coverage-html-report) | Publishes the Unity Code Coverage Report to the job page.         |\n| [unityTestRunner](#unity-test-runner)                                          | Uses Unity's Test Runner to execute the test suite.               |\n| [unityTestRunnerReport](#unity-test-runner-report)                             | Create a report from NUnit tests.                                 |\n| [tests.summary](#tests)                                                        | Get Junit test result summary.                                    |\n\n### Generic\n\n| Function                                                  | Summary                                                                               |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| [getBuildType](#get-build-type)                           | Retrieves the build type for the current running build.                               |\n| [setJobDisplayName](#set-job-display-name)                | Sets the display name based on the build type.                                        |\n| [git.branchName](#git-branch-name)                        | Get the current branch name.                                                          |\n| [git.commitSha](#git-commit-sha)                          | Get the full git commit sha for current commit.                                       |\n| [git.commitShaShort](#git-commit-sha-short)               | Get the short 7 character git commit sha for current commit.                          |\n| [git.getTrailerValue](#git-trailer-value)                 | Get the trailer value for the specified token.                                        |\n| [github.pullRequestComment](#github-pull-request-comment) | Creates or updates the Jenkins bot issue comment for the pull request.                |\n| [github.ownerRepo](#github-owner-repo)                    | Get the `owner/repo` part from the project's git url.                                 |\n| [github.pullRequest](#github-pull-request)                | Returns the pull request the current commit belongs to.                               |\n| [github.issueComments](#github-issue-comments)            | Retrieves all comments for an issue/pull request.                                     |\n| [github.createIssueComment](#github-create-issue-comment) | Create issue comment.                                                                 |\n| [github.updateIssueComment](#github-update-issue-comment) | Update issue comment.                                                                 |\n| [github.createCheckRun](#github-create-check-run)         | Create a check run.                                                                   |\n| [github.updateCheckRun](#github-update-check-run)         | Update a check run.                                                                   |\n| [influxdb.addMeasurement](#influxfb-add-measurement)      | Add a measurement for writing to InfluxDB.                                            |\n| [influxdb.write](#influxfb-write-measurements)            | Write all added measurements to InfluxDB.                                             |\n| [timers.start](#timers-start)                             | Creates and starts a new timer with the specified name.                               |\n| [timers.stop](#timers-stop)                               | Stops the timer with the specified name.                                              |\n| [timers.getDuration](#timers-get-duration)                | Gets the duration in ms between start and stop for the timer with the specified name. |\n| [utils.getDirectorySize](#utils-get-directory-size)       | Get the size of the provided directory in bytes.                                      |\n| [utils.getFileSize](#utils-get-file-size)                 | Get the size of the provided file in bytes.                                           |\n\n## Installation\n\nRead the [Extending with Shared Libraries \u003e 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`.\n\nWhen using the library in a Jenkinsfile, use a version specifier, to avoid surprises if future updates of the library introduces breaking changes.\n\n```groovy\n@Library('shared-library@v1.0.4') _\n```\n\n### Pipeline Utility Steps\n\nSeveral 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.\n\n### GitHub App\n\nFor 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\n\n## Pipeline Steps and Functions\n\nAn overview of the pipeline steps and functionality this shared library exposes.\n\n### Unity Specific\n\n#### Unity Build Number\n\nThis function parses Unity's Project Settings and returns the build number that has been set\nfor the Standalone build in Unity's `Project Settings \u003e Player \u003e Build`.\n\n```groovy\nsteps {\n    echo \"Unity build number: ${unityBuildNumber()}\"\n}\n```\n\n#### Unity Code Coverage Report\n\nRuns Unity's Code Coverage reporter. This assumes the Unity project has the Code Coverage package installed.\n\nThe reporter takes two parameters, `unityCodeCoverageReport(assemblyFilters, pathFilters)`.\n\n```groovy\npost {\n    always {\n        // Generate Reports from Unit Tests and Code Coverage.\n        unityCodeCoverageReport('+Bitbebop.Blitloop,+Dagobah.*,+Cosmos.*', '-**/Assets/Scripts/Input/GameInput.cs')\n    }\n}\n```\n\n#### Unity Code Coverage Report Summary\n\nParses `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.\n\nAvailable properties:\n\n-   coveredLines\n-   uncoveredLines\n-   coverableLines\n-   totalLines\n-   lineCoverage\n\n```groovy\ndef codeCoverage = unityCodeCoverageReportSummary()\necho  \"${codeCoverage.lineCoverage}\"\n```\n\n#### Unity Publish Code Coverage HTML Report\n\nPublishes the Unity Code Coverage Report so it's available from the job page.\n\n```groovy\npost {\n    always {\n        unityPublishCodeCoverageHTMLReport()\n    }\n}\n```\n\n#### Unity Test Runner\n\nUses Unity's Test Runner to execute the test suite.\n\n```groovy\nsteps {\n    unityTestRunner(\"EditMode\", \"iOS\", true, env.CODE_COVERAGE_ASSEMBLY_FILTER, env.CODE_COVERAGE_PATH_FILTERS)\n}\n```\n\n#### Unity Test Runner Report\n\nCreates a merged report from Unitys PlayMode and EditMode test files.\n\n```groovy\npost {\n    always {\n        unityTestRunnerReport()\n    }\n}\n```\n\n#### tests\n\nParses 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.\n\nAvailable properties:\n\n-   total\n-   failed\n-   skipped\n-   passed\n\n```groovy\ndef testSummary = tests.summary()\necho  \"${testSummary.passed}\"\n```\n\n### Common\n\n#### Get Build Type\n\nRetrieves 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.\n\n-   internal: `/feature/*`\n-   testflight: `/testflight/*`\n-   release: `/release/*`\n-   standard: `*`\n\n```groovy\nsteps {\n    echo \"Build type: ${getBuildType()}\"\n}\n```\n\n#### Set Job Display Name\n\nSets name for the running job based on git branch name.\n\n```groovy\nsteps {\n    setJobDisplayName()\n}\n```\n\n#### Git Branch Name\n\nGet the current branch name.\n\n```groovy\nsteps {\n    echo \"Git branch name: ${git.branchName()}\"\n}\n```\n\n#### Git Commit SHA\n\nGet the full git commit sha for current commit.\n\n```groovy\nsteps {\n    echo \"Git commit SHA: ${git.commitSha()}\"\n}\n```\n\n#### Git Commit SHA Short\n\nGet the short 7 character git commit sha for current commit.\n\n```groovy\nsteps {\n    echo \"Git short commit SHA: ${git.commitShaShort()}\"\n}\n```\n\n#### Git Trailer Value\n\nGet the [trailer](https://git-scm.com/docs/git-interpret-trailers) value for the specified token for the current commit.\n\n```groovy\nsteps {\n    echo \"Git commit message trailer value : ${git.getTrailerValue('some-token')}\"\n}\n```\n\n#### GitHub Pull Request Comment\n\nCreates or updates the Jenkins bot issue comment for the pull request.\n\nThis can be used to have a comment in the PR that Jenkins updates with current information about the build.\n\n```groovy\nsteps {\n    github.pullRequestComment(stringWithComment, 'jenkins[bot]')\n}\n```\n\n#### GitHub Owner Repo\n\nGet the \u003cowner/repo\u003e part from the project's git url.\n\n```groovy\ndef owner = github.ownerRepo()\n```\n\n#### GitHub Pull Request\n\nReturns the pull request the current commit belongs to.\n\n```groovy\ndef pr = github.pullRequest()\n```\n\n#### GitHub Issue Comments\n\nRetrieves all comments for an issue/pull request.\n\n```groovy\ndef comment = github.issueComments(42)\n```\n\n#### GitHub Create Issue Comment\n\nCreate issue comment.\n\n```groovy\ngithub.createIssueComment(42, \"some comment\")\n```\n\n#### GitHub Update Issue Comment\n\nUpdate issue comment.\n\n```groovy\ngithub.updateIssueComment(42, \"some updated comment\")\n```\n\n#### GitHub Create Check Run\n\nCreate a check run.\n\nStart a check run for a specific build build.\n\n```groovy\nsteps {\n    script {\n        github.createCheckRun('Build iOS', 'queued')\n    }\n}\n```\n\n#### GitHub Update Check Run\n\nUpdate a check run.\n\n```groovy\nsteps {\n    script {\n        github.updateCheckRun('Build iOS', 'in_progress')\n    }\n}\n\npost {\nfailure {\n    script {\n        github.updateCheckRun('Build iOS', '', 'failure')\n    }\n}\n\nsuccess {\n    script {\n        github.updateCheckRun('Build iOS', '', 'success')\n    }\n}\n```\n\n#### InfluxFB Add Measurement\n\nAdd a measurement for writing to InfluxDB. The data type for each field in teh measurement is set with a string.\n\n| value | Data type |\n| ----- | --------- |\n| `\"f\"` | float     |\n| `\"i\"` | integer   |\n| `\"s\"` | string    |\n\n```groovy\ninfluxdb.addMeasurement(\"build\",\n    [\n        platform: platform,\n        build_type: buildType\n    ],\n    [\n        code_coverage: [\"f\", coverage.lineCoverage],\n        size: [\"i\", size],\n        duration_unity: [\"i\", timers.getDuration(\"Unity.${platform}\")],\n        duration_xcode: [\"i\", timers.getDuration(\"Xcode.${platform}\")],\n        jenkins_build_number: [\"i\", currentBuild.number],\n        unity_build_number: [\"i\", unityBuildNumber()],\n        commit_sha: [\"s\", env.GIT_COMMIT_SHA_SHORT]\n    ]\n)\n```\n\n#### InfluxFB Write Measurements\n\nWrite all added measurements to InfluxDB.\n\n```groovy\nwithCredentials([string(credentialsId: 'influxdb', variable: 'INFLUXDB_TOKEN')]) {\n    influxdb.write(env.INFLUXDB_HOST, env.INFLUXDB_ORG, env.INFLUXDB_BUCKET, INFLUXDB_TOKEN)\n}\n```\n\n#### Timers Start\n\nCreates and starts a new timer with the specified name.\n\nMultiple timers can be created and started to store the duration for different steps of the pipeline.\n\n```groovy\ntimers.start(\"unity.${platform}\")\nbuildUnity(platform)\ntimers.stop(\"unity.${platform}\")\n```\n\n#### Timers Stop\n\nStops the timer with the specified name.\n\n```groovy\ntimers.start(\"unity.${platform}\")\nbuildUnity(platform)\ntimers.stop(\"unity.${platform}\")\n```\n\n#### Timers Get Duration\n\nGets the duration in ms between start and stop for the timer with the specified name.\n\n```groovy\necho \"Unity iOS Build Duration: ${timers.getDuration('unity.iOS')}\"\n```\n\n#### Utils Get Directory Size\n\nGet the size of the provided directory in bytes.\n\n```groovy\ndef size = utils.getDirectorySize('build.app')\n```\n\n#### Utils Get File Size\n\nGet the size of the provided file in bytes.\n\n```groovy\ndef size = utils.getFileSize('build.ipa')\n```\n\n## Development\n\nGradle is used to test the pipeline during development.\n\n### Running Tests\n\nThe test suite is executed with:\n\n```sh\n./gradlew test\n```\n\nThen gradle is executed for the first time in a session a daemon is started. Manage the daemon with these commands.\n\n```sh\n## See running daemons\ngradle --status\n\n## Stop running daemons\ngradle --stop\n```\n\n### macOS\n\nGradle 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.\n\n```\nexport JAVA_HOME=/usr/local/opt/openjdk@17\n```\n\n### Debug Output\n\nDuring development it can be useful to get output from tests to the console.\n\n```groovy\n@Test\nvoid foo_SomeBar_GetSomeBaz() {\n    println(someObjectToDebug)\n}\n```\n\nEnable log info level to display `println` statements in the test output.\n\n```sh\n./gradlew test --info\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartstorm%2Fjenkins-shared-library-unity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartstorm%2Fjenkins-shared-library-unity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartstorm%2Fjenkins-shared-library-unity/lists"}