{"id":23651866,"url":"https://github.com/microfocus/octane-ci-java-sdk","last_synced_at":"2025-09-01T02:32:13.410Z","repository":{"id":17558816,"uuid":"79714247","full_name":"MicroFocus/octane-ci-java-sdk","owner":"MicroFocus","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-30T13:37:07.000Z","size":8164,"stargazers_count":5,"open_issues_count":2,"forks_count":24,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-08-15T01:38:15.897Z","etag":null,"topics":["octane"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MicroFocus.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2017-01-22T11:40:49.000Z","updated_at":"2025-08-13T11:16:26.000Z","dependencies_parsed_at":"2024-01-29T16:10:16.369Z","dependency_job_id":"cbabc080-333c-4b22-a3da-a14e9ec5c8fa","html_url":"https://github.com/MicroFocus/octane-ci-java-sdk","commit_stats":{"total_commits":1027,"total_committers":68,"mean_commits":"15.102941176470589","dds":0.6475170399221032,"last_synced_commit":"8972fdef01cbd39042b82ba0b5e549756ffc2325"},"previous_names":["hpsoftware/octane-ci-java-sdk"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/MicroFocus/octane-ci-java-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroFocus%2Foctane-ci-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroFocus%2Foctane-ci-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroFocus%2Foctane-ci-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroFocus%2Foctane-ci-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MicroFocus","download_url":"https://codeload.github.com/MicroFocus/octane-ci-java-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroFocus%2Foctane-ci-java-sdk/sbom","scorecard":{"id":60830,"data":{"date":"2025-08-11","repo":{"name":"github.com/MicroFocus/octane-ci-java-sdk","commit":"00f053e436026015f028502ca4fe7d0b3deb1a78"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.7,"checks":[{"name":"Maintained","score":6,"reason":"8 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/main.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":9,"reason":"Found 10/11 approved changesets -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/MicroFocus/octane-ci-java-sdk/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/MicroFocus/octane-ci-java-sdk/main.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/main.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/MicroFocus/octane-ci-java-sdk/main.yml/master?enable=pin","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.5.38 not signed: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/13345926","Warn: release artifact 1.5.27 not signed: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/12604461","Warn: release artifact v1.5.19 not signed: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/11727188","Warn: release artifact v1.5.6 not signed: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/11294997","Warn: release artifact v1.5.4 not signed: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/10047776","Warn: release artifact v1.5.38 does not have provenance: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/13345926","Warn: release artifact 1.5.27 does not have provenance: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/12604461","Warn: release artifact v1.5.19 does not have provenance: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/11727188","Warn: release artifact v1.5.6 does not have provenance: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/11294997","Warn: release artifact v1.5.4 does not have provenance: https://api.github.com/repos/MicroFocus/octane-ci-java-sdk/releases/10047776"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":9,"reason":"1 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-h46c-h94j-95f3"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-15T01:39:52.122Z","repository_id":17558816,"created_at":"2025-08-15T01:39:52.122Z","updated_at":"2025-08-15T01:39:52.122Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273065038,"owners_count":25039274,"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","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["octane"],"created_at":"2024-12-28T16:48:43.893Z","updated_at":"2025-09-01T02:32:12.082Z","avatar_url":"https://github.com/MicroFocus.png","language":"Java","readme":"[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![AppVeyor](https://img.shields.io/appveyor/ci/OctaneCIPlugins/octane-ci-java-sdk/master.svg?logo=appveyor)](https://ci.appveyor.com/project/OctaneCIPlugins/octane-ci-java-sdk/branch/master)\n\n\n# SDK for CI Plugins to integrate with ALM Octane\n\n## Introduction\n\nOctane's CI Plugin Development Kit provides an easy and robust way to integrate CI Environment with [ALM Octane](https://software.microfocus.com/en-us/products/alm-octane/overview) application server.\nIn vast majority of cases, SDK will be used as a part of a bigger integration unit - CI server's plugin/addon, therefore we'll be referring to the whole integration component as **CI Plugin** henceforth.\n \nSDK knows to establish steady connectivity (by means of long polling over HTTP/S protocol) with ALM Octane, thus being able to handle tasks submitted from ALM Octane and return results if/where relevant.\nThere is a predefined set of tasks that are supported by such a flow (discover projects/jobs or job's/project's structure, trigger build etc).\n\nThere are 3 architectural entities that are essential to understand in order to work with SDK easily:\n1) `OctaneSDK` is a top level entry point, SDK manager. This class provides static methods to add, get or remove `OctaneClient` instances.\nRuntime flow will typically start from the point when `addClient` method of `OctaneSDK` is called\n2) `OctaneClient` is the actual 'job doer'.\nIn a normal functional cases there is a need to init only one instance of `OctaneClient`, yet this class if fully thread safe and multiple instances of it may be intact.\nEach `OctaneClient` is designed to provide full functionality of work with a single specific SharedSpace/Tenant of Octane server.\nClient is responsible for establishing the connectivity with Octane, receive and dispatch tasks coming from Octane and provide services to push contents to Octane.\n3) In order to inter-operate with the 'hosting' CI environment, SDK employs a Service Provider Interface pattern (SPI).\nSPI consists of a single interface, `CIPluginServices`, that is required to be implemented by an SDK's consumer and instance of which is a must parameter of SDK's `OctaneClient` initialization method.\n\nTypical SDK-based ALM Octane integrated CI Plugin development would walk along the following path:\n1. [Including](#include-in-your-project) the SDK into the CI Plugin (be it new or an existing one) as maven dependency \n2. Implementing an SPI interface/s (or extending `CIPluginServicesBase` abstract class, convenient for partial implementation)\n3. Adding [`OctaneClient` initialization](#initialization) to the initialization flow of the CI Plugin\n4. Hooking into the specific CI environment's event mechanism in order:\n   1. to [push builds' events](#updating-alm-octane-with-ci-events) to ALM Octane\n   2. to [push builds' artifacts](#providing-test-results) (tests results etc) to ALM Octane\n\nThis Java SDK project has two sub-projects:\n- **integrations-sdk**: the main source of the CI Plugin SDK\n- **integrations-dto**: the definition and building factory of all DTO objects used for communication with ALM Octane\n\nSee the [Javadoc](#creating-javadoc) for more information about the CI Plugin SDK APIs.\n\nSee [change log](changelog.md) for the released versions of this library.\n  \n  \n## Compiling the Project\n\nThe easiest way to compile the project is to use [Maven](https://maven.apache.org/) and run the following command from the root directory:\n```\nmvn clean install\n```\n  \n  \n## Creating JavaDoc\n\nTo create Javadoc, run the following [Maven](https://maven.apache.org/) command from the project root directory:\n```\nmvn javadoc:aggregate\n```\n\u003e_This creates a javadoc site in the `/target/site/apidocs/index.html`_\n  \n  \n## Include in Your Project\n\nAdd the following dependency to the `pom.xml` to use this SDK in your project (providing the relevant version, of course):\n```\n\u003cdependency\u003e\n    \u003cartifactId\u003eintegrations-sdk\u003c/artifactId\u003e\n    \u003cgroupId\u003ecom.hpe.adm.octane.plugins\u003c/groupId\u003e\n    \u003cversion\u003e${integrations-sdk.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\n## Usage Examples\n\nThe following CI Plugins are already using **CI Plugin SDK for ALM Octane** to connect and communicate with ALM Octane:  \n[Octane Bamboo Plugin](https://github.com/MicroFocus/octane-bamboo-plugin)  \n[Octane TeamCity Plugin](https://github.com/MicroFocus/octane-teamcity-plugin)\n\n\n## Initialization\n\nTo start using the SDK's services, first initialize an `OctaneClient` instance. This class provides the main entry point of interaction between the SDK and its services, and interaction between the concrete CI Plugin and its services:\n```java\nOctaneSDK.addClient(new MyPluginServices());\n```\nThe `addClient()` method expects to get an instance of a valid implementation of the `CIPluginServices` SPI.\nThis object is actually a composite API of all the endpoints to be implemented by a hosting CI Plugin for an ALM Octane use cases.\nSame instance of `CIPluginServices` MAY NOT be used for more than a single `OctaneClient` initialization.\nMoreover, different instances of `CIPluginServices` MAY NOT provide the same `instanceId` value, the one that is effectively identifying `OctaneClient` instances.\n\n\n## Communicating with ALM Octane using Data Transfer Objects (DTO)\n\n[Data transfer object](https://en.wikipedia.org/wiki/Data_transfer_object) (DTO) is a design pattern used to transfer data between software application subsystems. We use DTO objects to communicate data to ALM Octane.\n\nAny DTO in the system should be created using `DTOFactory`:\n```\nT dto = DTOFactory.getInstance().newDTO(Class\u003cT\u003e targetType);\n```\n\n\n## Updating ALM Octane with CI Events\n\nMost/all of the CI servers provide a means to hook into their own events system, thus providing convenient extensibility points for any addon/plugin willing to leverage the CI data further.\nUpon a CI event, the CI Plugin should update ALM Octane using the `EventsService`. The steps are:\n\n1. Subscribe to CI events by means of underlying/hosting CI system\n2. Create ALM Octane's internal `CIEvent` DTO from the data provided by the CI system\n3. Provide this DTO to the `publishEvent` method of `EventsService`:\n```java\nCIEvent ciEvent = DTOFactory.getInstance().newDTO(CIEvent.class)\n      .setEventType(eventType)\n      .setCauses(causes)\n      .setProject(project)\n      .setProjectDisplayName(displayName)\n      .setBuildCiId(buildCiId)\n      .setEstimatedDuration(estimatedDuration)\n      .setStartTime(startTime)\n      .setPhaseType(phaseType);\n\noctaneClient.getEventsService().publishEvent(ciEvent);\n```\n\nOne of the capabilities of `CIEvent` is to transfer SCM data as part of it.\nSCM data provided by most/all of the CI servers taking it directly from the Source Control Management tool (Git, Mercurial etc) and mostly comprises from all of the commits that was introduced into the code and built in the inspected build (aka diff from the last commit of the previous build)/\nSCM data can greatly leverage integration with ALM Octane, which knows to analyze it, link it's contents to relevant Work Items (by commit patterns), provide statistical insights, failure analysis and more of it.\n\nPay attention, that although SCM data may be posted in the later stages of the build/pipeline run, it is always better to push the data to ALM Octane as soon as it available.\nAdd an SCM data to the event in the following way:\n```java\nciEvent.setScmData(scmData);\n```\n\nIf at the point of time, where some CI event is being pushed to ALM Octane, CI Plugin already knows that tests results are/will surely be available for this build, notifying ALM Octane about this would help to improve the performance and responsiveness of the flow.\nTo do so, please use the following API of `CIEvent` DTO:\n```java\nciEvent.setTestResultExpected(true);\n```\n\n## ALM Octane Pipeline Structure\n\nALM Octane pipelines represent the flow of the CI server jobs and steps. Pipeline provides a clear, multi-level, analytic view of specific CI process, CI runs and their status so you can track product quality and progress.\n\nALM Octane pipeline supports a hierarchical structure of pipeline nodes. Any `PipelineNode` can contain a list of internal phases and list of post-build phases. Each `PipelinePhase` in turn contains a list of child pipeline nodes.\n\nPipeline nodes in internal phases represent CI nodes that complete their execution before post-build phases start to execute. Each internal phase should contain nodes that are running in parallel.\n\nThis structure is used for correct pipeline representation in ALM Octane. This way in ALM Octane, it is possible to see the flow of steps in the CI server, including which steps run in sequence and which steps run as parts of other steps.\n\n\n## Providing CI Build Information\n\nThe ALM Octane server may ask for a specific build information of some pipeline. To provide the information, implement two ```CIPluginServices``` methods:\n\n```java\nSnapshotNode getSnapshotByNumber(String ciJobId, String buildCiId, boolean subTree)\n```\n\u003e_This provides a snapshot of the specified build of the specified job._\n\n```java\nSnapshotNode getSnapshotLatest(String ciJobId, boolean subTree)\n```\n\u003e_This provides a snapshot of the latest build of the specified job._\n\n\nThe main DTOs for CI build snapshots are `SnapshotNode` and `SnapshotPhase`. These provide the same hierarchical structure described in the [Pipeline Structure](#alm-octane-pipeline-structure) section and allow the ALM Octane user to see the build number, the last run date, the run status, and the duration of the run.\n\n\n## Providing Test Results\n\nWe are about CI events hooking again.\nOnce SDK driven integration got some CI event where it can safely retrieve tests results of a build - usually that would be a finished/completed event of any build, thus we are talking on the level of a single build - it should push tests results to ALM Octane.\n\nThe preferred flow is somewhat asynchronous and it is crucial to understand it, so here is the detailed description:\n1. When tests result are fully accessible, CI Plugin should ensure, that those may be identified and accessed later on; for identification we use a notion of `jobCiId` and `buildCiId` which are a simple strings; pay attention, that in some/most CI systems tests results (with their full data, like duration, exceptions etc) are not available for a prolonged period of time, in such a cases it is required to store this data somewhere for later retrieval\n2. Next, CI Plugin should 'notify' the SDK that tests results are available for such a `buildCiId` of such a `jobCiId`, whatever they are, using the following API:\n   ```java\n   octaneClient.getTestsService().enqueuePushTestsResult(someJobCiId, someBuildCiId);\n   ```\n3. SDK will enqueue this info internally (not persisted, as of now) and somewhat later, usually almost immediately, but it depends on the system load of course, turn back to an SPI and will ask for a full report of tests results of the said above `jobCiId`/`buildCiId`; CI Plugin is expected to be able to retrieve the correct tests results (probably stored somewhere, as we mentioned in punkt 1 above) and return them; to be sure, relevant SPI method is:\n   ```java\n   TestsResult getTestsResult(String jobCiId, String buildCiId);\n   ```\n   \u003e_`TestResult` DTO should contain a list of all test runs (`TestRun`) that were executed in the specified build of the specified job.\n   Each `TestRun` object represents a run of a single test. It contains all information about the test, run's result (`TestRunResult` enum) and the error information if failed.\n   URL to the test run report page can be provided with the `setExternalReportUrl()` method._\n4. SDK will further perform the actual push to the ALM Octane\n\n\n\n\u003e_Pay attention, that usually executing time consuming actions within the CI event call effectively means holding the main CI system execution thread, since most of the CI system's events are executing on the main thread.\nDon't do that._\n\n\n## Disclamer update\nCertain versions of software accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company.\nThis software was acquired by Micro Focus on September 1, 2017, and is now offered by OpenText. \nAny reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrofocus%2Foctane-ci-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrofocus%2Foctane-ci-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrofocus%2Foctane-ci-java-sdk/lists"}