In the following documentation, the OpenText Core Software Delivery Platform and OpenText Software Delivery Management will collectively be referred to as 'the product'.
This is a custom plugin which facilitates communication between Azure DevOps and the product (formally known as ALM Octane/ValueEdge) regarding CI/CD. The extension will monitor and reflect the pipeline activity into the product.
- 1. Introduction
- 2. Table of Contents
- 3. Requirements
- 4. Extension configuration
- 5. Pipeline interaction
- 5.1. Create a new pipeline with the Octane start and end tasks through YAML editing (implicit Azure job)
- 5.2. Create a new pipeline with the Octane start and end tasks through classic editor (implicit Azure job)
- 5.3. Create a new pipeline with the Octane start and end tasks through YAML editing (explicit Azure jobs)
- 6. Displaying Cucumber Gherkin test results into the product
- 7. Configuring test runner pipeline
- 8. Useful Configurations
- 9. Known issues and limitations
- 10. Change logs
- At least one Azure Devops agent allocated for running the pipeline
- The Azure DevOps extension version should be 1.0.0.8 or higher (certain features require a newer version - see documentation)
- The product version should be 16.1.200 or higher
- API access to the product with CI/CD Integration or DevOps Admin roles
- In Azure DevOps, click on "Manage extensions":
- Then click on click on "Browse marketplace":
- Search for "Octane" and filter by "Azure Pipelines":
- Click on "Get it free":
- Choose the Azure DevOps organization you want to install this extension into and press "Install":
- Go back to your organization by pressing the "Proceed to organization" button:
Before you can add a new service connection, please make sure you have a valid API ACCESS key and secret set in the product. You can follow the steps below to create one:
- Firstly, go to the space and in the API Access tab press the "+ API access" button:
- Fill in all required data, like name, and don’t forget to select the role for CI/CD Integration in the required workspace:
- In the displayed popup, press copy and save your newly created API Access, but be careful, after closing this prompt, you won't be able to visualise these variables again, so its highly recommended to save these values somewhere:
- Firstly, go back in Azure DevOps, and go to "Project settings" in the bottom left corner:
- Click on the "Service connections" available in the "Pipeleines" tab:
\
- Press the “Create service connection” button:
- Select the ALM Octane connection type:
- Fill in all fields required in the form which appears, as follows:
Server Url - the URL of the Octane the service connection will point to. Make sure to include the sharedspace/workspace query parameter (p=1002/1002)
Instance ID - the name you expect to see in CI Servers grid in DEVOPS tab for a specific space, like in the example:
Authentication - The API Access key and secret which are created inside the shared space, the creation of which was presented earlier in the guide.
Service connection name - The name to be used anywhere inside Azure DevOps to reference this service connection.
Grant access permission to all pipelines - Selecting this checkbox will make this service connection available for all pipelines for usage.
5.1. Create a new pipeline with the Octane start and end tasks through YAML editing (implicit Azure job)
- Go to Pipelines and press Create Pipeline:
- Select the source code repository type you use, in this case we will use the local Azure Repos Git:
Note
Note that depending on the repository type you select, there might be different steps to execute.
- Select the actual repository:
- Edit your YML if you require, and press Save and Run:
- Go to Pipelines, where you should see your new pipeline. It should be marked green, as the job succeeded:
- Press on the pipeline and edit it:
- Add the ALM Octane Job Start and ALM Octane Job End. You must make sure to add them together because otherwise the pipelines will not show properly in the product. Job start is required in order to create the CI Server and Pipeline in the product and mark it as running. Job end is required in order to let the product know that the pipeline ended. This should be the last task inside your Azure DevOps pipeline. Make sure you put your cursor in the right location before adding the task as it will generate a YAML task entry directly in the position where your cursor was before you click on the task.
- You need to know your workspace ID(s) within the product where you want your pipeline to be created and updated. You can find it in two ways:
- From the URL of the product instance you access, usually it is the second integer, as you can see from this example mock link: https://yourOctaneDomain.com/ui/?p=1001/1002
- If you have shared space admin rights, go to Spaces within the product and press the Edit Workspace button
- After finding the respective workspace id, make sure to paste it in the form that opens when you select either the start task or the end task.
- In the end you should have in your YAML file something like below:
Caution
Make sure to add the following condition inside both the start task and the end task: condition:always(). This will make sure that if you cancel a pipeline run, the respective run will still be replicated into the product and will appear with the status set to "Aborted". After adding this condition, the tasks should look like this:
- task: octane-start-task@1
condition: always()
inputs:
OctaneServiceConnection: 'AzureExtensionPipelineServiceConnection'
WorkspaceList: '1002'and
- task: octane-end-task@1
condition: always()
inputs:
OctaneServiceConnection: 'AzureExtensionPipelineServiceConnection'
WorkspaceList: '1002'- Press the save button in the top right corner:
- Execute the pipeline by pressing Run:
- You should observe that the job was successful, like below:
- If you click on the job you can see all its tasks. If you press, for example, on octanestarttask, you can observe logs indicating that the connection to the product was successful:
- Back in the product, you can check two things that were created successfully:
- That the pipeline was actually created
- If you have shared space admin role, see that you have a new entry in the CI Servers grid, with the Instance ID matching the one you have previously configured:
5.2. Create a new pipeline with the Octane start and end tasks through classic editor (implicit Azure job)
- Go to the Pipelines and find the hyperlink as below:
- In the next step, choose the right team project, repository and branch:
- Choose the right template (suppose you want a Maven configuration to build Java code):
- Fill in all required information if default values are not satisfactory for you, and select Save:
- Save the pipeline in a folder which you want:
- Go to Pipelines and find your new pipeline and try to run it. You need a valid project in that repository with a valid pom.xml and surefire plugin configured, so that the actual tests are triggered and the report is published to the product.
- Observe the execution results:
\
- If you will go inside the pipeline, you can observe the following:
- When you click on the run, you should see a view similar to the one below:
- In “Agent job 1”, press on Maven pom.xml and scroll down. You can observe:
- The next step is to add the ALM Octane tasks. Go back and press “Edit” in order to edit the pipeline and add the Octane tasks:
- In the newly displayed view, press the plus sign on the right of “Agent Job 1” in order to reveal all possible tasks to be added:
- Add the start task:
- The task should be added to the end of the list, and now you should position it before all other tasks. Additionally, you need to configure it:
- Click on the button on the right and configure the task:
- Drag and drop the ALM Octane Job Start and position it first in the list:
- Do the same thing for the ALM Octane Job End, so that you end up with the following pipeline. Press “Save & queue”:
- Add a relevant comment to the save, and press the “Save and run” button:
- Wait for the pipeline to run. Then, open “Agent Job 1” and observe that you have two additional ALM Octane tasks that were executed:
- Now you can go to the product and verify that the pipeline was created and shows the results:
5.3. Create a new pipeline with the Octane start and end tasks through YAML editing (explicit Azure jobs)
Previous chapters focused on the demonstration of how to create pipelines with Octane tasks inside them. This is ok if you do not need complex pipelines with multiple jobs inside them, or you are just testing how the extension might fit your needs. For more complex scenarios where multiple jobs are used and the pipelines already exist, tasks under existing jobs might not be a solution. Suppose you have the following YAML, which contains a simple task of building a maven project specified under an unnamed job (in theory you might have many jobs here, but for the sake of simplicity, we will work with only one):
# Maven
# Build your Java project and run tests with Apache Maven.
# Add steps that analyze code, save build artifacts, deploy, and more:
# https://docs.microsoft.com/azure/devops/pipelines/languages/java
trigger:
- main
jobs:
- job:
pool: 'Default'
steps:
- task: Maven@3
inputs:
mavenPomFile: 'pom.xml'
mavenOptions: '-Xmx3072m'
javaHomeOption: 'JDKVersion'
jdkVersionOption: '1.8'
jdkArchitectureOption: 'x64'
publishJUnitResults: true
testResultsFiles: '**/surefire-reports/TEST-*.xml'
goals: 'package'If you want ALM Octane Start Task and End Task to be included as separate jobs, do the following:
- Give a name to your existing job (or jobs, if multiple).
- Add a new job at the same level as your existing job, and place your cursor on the next line after “steps:”:
- Press on the ALM Octane Job Start to be added:
- Fill in the required fields (refer to previous chapters for pre-requisites, explanation, and examples):
- You should end up with the following block of code:
- Add the ALM Octane Job End in the same way as for start, with the difference that you need to have the “dependsOn” property set to the list of all existing jobs, including Octane Start Job. This is required because jobs might run in parallel, and to make sure that End job runs last, we need to set the dependencies on all other jobs:
- As a last step, set “dependsOn” property of your jobs to depend on the AlmOctaneStartJob (or whatever name you’ve assigned to it), as follows:
- In the end, you should have the YAML file similar to the one below:
# Maven
# Build your Java project and run tests with Apache Maven.
# Add steps that analyze code, save build artifacts, deploy, and more:
# https://docs.microsoft.com/azure/devops/pipelines/languages/java
trigger:
- main
jobs:
- job: MavenBuildJob
pool: 'Default'
dependsOn:
- AlmOctaneStartJob
steps:
- task: Maven@3
inputs:
mavenPomFile: 'pom.xml'
mavenOptions: '-Xmx3072m'
javaHomeOption: 'JDKVersion'
jdkVersionOption: '1.8'
jdkArchitectureOption: 'x64'
publishJUnitResults: true
testResultsFiles: '**/surefire-reports/TEST-*.xml'
goals: 'package'
- job: AlmOctaneStartJob
condition: always()
pool: 'Default'
steps:
- task: octane-start-task@1
inputs:
OctaneServiceConnection: 'VMOctaneServiceConnection'
WorkspaceList: '1002'
- job: AlmOctaneEndJob
condition: always()
pool: 'Default'
dependsOn:
- AlmOctaneStartJob
- MavenBuildJob
steps:
- task: octane-end-task@1
inputs:
OctaneServiceConnection: 'VMOctaneServiceConnection'
WorkspaceList: '1002'- Save and run the pipeline, and you should see something similar to below:
- Because we specified the dependencies between the jobs, AlmOctaneStartJob should run first, MavenBuildJob second, and AlmOctaneEndJob should be last:
Now you can create complex scenarios with different jobs. Make sure you understand the dependencies and current limitations of the Azure DevOps pipeline and the extension.
- Create a pipeline job for running the tests.
- Make sure to configure the Maven task to use the OctaneGherkinFormatter when running the tests, and where to store the results as below. The formatter specifies the location and name of the generated xml file containing the report.
- Fill in the Cucumber report destination path field when configuring the ALM Octane Job End task. This must point to the same directory as specified for the GherkinFormatter. Note that the path must be filled in starting with the source code repo root directory.
- Run the pipeline and check if all steps have been completed successfully. The End Job task should display the fact that the test results have been found and processed as below:
- The results can be observed in the product in the Pipelines section:
- Create a pipeline job for running the tests.
- Make sure to configure the Maven task to use the OctaneGherkinFormatter when running the tests, and where to store the results as below. The formatter specifies the location and name of the generated xml file containing the report.
- Fill in the Cucumber report destination path field when configuring the ALM Octane Job End task. This must point to the same directory as specified for the GherkinFormatter. Note that the path must be filled in starting with the root directory of the project.
- Run the pipeline and check if all steps have been completed successfully. The End Job task should display the fact that the test results have been found and processed like below:
- The results can be observed in the product in the Pipelines section:
Besides pipeline runs, you can also configure test runners using this extension, by making use of the octane-test-runner-start-task@1. Naturally you will not be creating another pipeline in the product, but rather a test runner that you can assign test suites to and run them from the product and see the results in both Azure DevOps and the product. To do that you need to follow the next steps:
- Firstly, as in the previous steps, you need to create a new pipeline:
- Choose your desired source cod repository option, but keep in mind that there might be different steps to execute, depending on the repository type you selected.
- Select the actual repository:
- Edit your yml file if you need to do so, and press the Save and Run:
- Go to Pipelines, where you should see your new pipeline:
- Press on the pipeline and edit it:
- Here is where things are a bit different. Instead of selecting the usual octane-start-task, make sure to select the ALM Octane Test Runner Job Start task. Make sure you put your cursor in the right location before adding the task as it will generate a YAML task entry directly in the position where your cursor was before you click on the task.
- You will need to have an existing service connection, to know your workspace id and also select a framework convert type that best suits your needs:
Normally you should end up with something like this. The end task remains the same
- task: octane-test-runner-start-task@1
inputs:
OctaneServiceConnection: 'octaneConnection'
WorkspaceList: '1002'
Framework: 'junit'- Make sure to save the modifications.
- Ensure the following variables are defined in your Azure DevOps pipeline for automated test execution:
Note
If you are having trouble configuring variables, please refer to 8.2 Running pipelines with variables
testsToRun(type: string)suiteId(type: number)suiteRunId(type: number)executionId(type: number)- For numerical variables, it is recommended to set a default value of
0.
-
Configure the
testsToRunConversion. To run the selected tests, configure a job or step to convert the testsToRun value into the format required by your test framework. This logic should be handled in your test automation setup. For reference: @opentext/sdp-sdm-tests-to-run-conversion -
Run the pipeline. After the run was completed, you should see a new test runner instance in the product, in the Spaces tab, in your workspace in the DevOps tab:
From here the the possibilities depend on your needs. For example, you can assign multiple tests to a test suite and assign that test suite to the test runner. This way, you can run those tests from the product via the test runner and see the results in Azure DevOps. For more details on how to do that, make sure to check the documentation on test suites and test runner:
Caution
If any of the previous steps failed and you aren't able to run the test runner pipeline in Azure Devops, make sure that in Azure project settings, in the Settings tab, set "Limit variables that can be set at queue time" to OFF.
- In order to start runs from the product, you need to do some additional configuration steps. First of all, in Azure DevOps you need to go to: User settings -> Personal access tokens:
- We will need to generate such a token, with the corresponding rights, in order to be able to run the pipeline from the product. Press on the "New Token" button
- Make sure to name this token and also in the Scopes tab, in the Build subsection, select the Read & execute rights, and then press Create
- Copy the generated value, and make sure you save it somewhere as we will need it in the next steps:
- Go back to the product, in the Spaces tab, select the workspace you associtated your pipeline with, then select the Credentials tab:
- Go ahead and press the + Credentials button and then paste the value generated by the Personal access token from Azure DevOps into the password field. You can name this credentials instance as you see fit:
Note
The User Name field does not have any correlation with any usernames that you use to login to either Azure DevOps, or the product. It doesnt have any impact on how the credentials get stored, so you can name it however you see fit.
- Then go to the DevOps section where your CI Server instance should be visible. The next step would be to set the recently created Credentials to your CI Server, in order to be able to run your pipelines from the product. By default, the Credential column is not visible so you need to make it so:
- You should now see an additional empty column. Make sure to double click on that empty value, and a dropdown should open. Select your recently created credential:
- Now you can go back in the Pipelines in the product, select the 3 points icon from the pipeline you want to run and then press Run. You should then be able to see your run in Azure DevOps.
Azure DevOps pipelines support the use of variables to make workflows more dynamic, reusable, and configurable. Variables can be defined at multiple levels—pipeline, stage, job, or step—and passed between tasks or used to customize behavior at runtime. This section outlines how to declare, reference, and override variables when running pipelines. These variables in turn will be visible in the product and when running the pipeline from it, you will also be able to set their values accordingly.
- Firstly you need to navigate to a pipeline and press the Edit button. Then near the Run button you will see the Variables button, which will open this interface. Press New variable
- Then set a name and optionally a default value for your variable and select whether you want this variable to be secret or not.
Note
Secret variables will not be sent to the product and henceforth, will not be visible when checking details about the pipeline runs or the pipeline itself in the product.
Caution
Make sure to check the box for the Let users override this value when running this pipeline option. This will enable you to set a value for this variable when running the pipeline from the product.
-
Press OK and then you will see your variable.
-
Now if you want to run your pipeline from the product you will be met with this prompt. Give a value to that variable and the press Run
A very useful feature is enabling debug messages, which not only gives you more insight into what happens behind the scenes, but it can also help you in figuring out what went wrong with a run. To enable this kind of messages, you need to create pipeline variable with the following values:
name = ALMOctaneLogLevelvalue = DEBUG
If you're not sure how to create such varibales please refer to 8.2 Running pipelines with variables
Now whenever you run any pipeline and check the logs, you will notice that there are additional log messaeges, compared to previous runs, distinguished by the color purple:
-
ALM Octane Connection Verifier is non-functional. This will be removed in a future version.
-
When creating the pipeline with YAML and adding the ALM Octane tasks, the label is not displayed properly (octanestarttask)
-
The ALM Octane tasks might show as GREEN even if these have errors, like:
- If you specify a wrong URL, for example, like in the case http://192.168.1.129:9090/?p=1001/1002, meaning skipping /ui/ part.
- If Octane Server is down, you might see in the Octane start task log: “[ERROR]{"code":"ECONNREFUSED","errno":"ECONNREFUSED","syscall":"connect","address":"192.168.1.129","port":9090}”
- If you specified wrong credentials or the API key was revoked in Octane.
-
All tests which are running with surefire plugin, for example, regardless of their nature, will be published to Octane as Automated runs.
-
In comparison with Jenkins, for example, currently the extension does not support injecting events of jobs/sub-jobs that are running in Azure. This means that you will have only one job injected in Octane which will be the Octane Start task, and which will show as completed with the related status when the pipeline ends with the Octane End Task. This behavior is limited because of the way Azure DevOps Pipelines currently work.
-
YAML is based on TABs, and as such, if you miss a TAB you might end up with a wrongly formatted YAML file and as such the pipeline will not work.
-
After the Azure pipeline is created in ALM Octane, follow the next steps to be able to run the pipeline from the ALM Octane side, as described here: https://admhelp.microfocus.com/octane/en/25.1/Online/Content/AdminGuide/how_config_CI_plugin.htm#mt-item-5
-
If you cancel a pipeline run, before the initialization job takes place, you will not see that particular run in the product with the status "Aborted". This behaviour is expected since neither the start task or the end task have time to execute, given the quick cancelation of the run.
- Added support for aborted pipeline runs
- Secret variables set in Azure DevOps will not be shown in Octane
- Added project name into pipeline name
- Upgraded ALM Octane Js SDK Version
- Fix defects
- Add option to define pipeline name create on ALM Octane or use it's full folder path.
- Fix issue that not all test result was sent to ALM Octane.
- Fix issue that test result was sent without escape characters.
- Added support to Testing Framework for running test using test runners starting from version 23.4 of ALM Octane.
- Added possibility to skip creation of ALM Octane pipelines starting from version 23.4 of ALM Octane.
- Rebranding to Open Text
- Fix defects
- Fix Documentation
- Fix defects
- Updated to major version. The integration (previously tech preview) is now fully supported.
- Fix test run report path that send to Octane, supported from version 16.1.100 of Octane
- Fix defects
- Added support for multi-branch pipelines:
ALM Octane automatically creates a corresponding child pipeline whenever a new branch is built for the first time.
Existing pipelines are upgraded to be multi-branch.
- Send parameters structure to Octane, from version 16.1.18.
- Send parameters values executed to Octane, from version 16.1.18.
- Fix defects
- Update Octane CI Server plugin version.
- Ability to run Azure DevOps pipelines from within ALM Octane, from version 16.0.400.
- Report to Octane duration of the pipeline run
- handle multi changes per commit
- report to Octane max number of commits the Azure devops API return
- Fix issue with unknown change type on commits, and added logs
- Added support for Gherkin injection
- Various other improvements, including bug fixes and logs
- Fixed 401 error in tasks not showing as failed
- Homogenized public and private extensions. Currently, besides Azure DevOps required manifests and versions there will not be any difference between the private and the public extension.
- Other non functional improvements