1. Introduction 🚀

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 GitHub Action which facilitates communication between GitHub and the product (formerly known as ALM Octane/ValueEdge) regarding CI/CD. The action will monitor an automation workflow and will reflect it into the product.

2. Table of Contents

• 1. Introduction
• 2. Table of Contents
• 3. Requirements
• 4. Workflow Configuration
  • 4.1 Full YML Example
  • 4.2 Workflow Parameters
  • 4.3 Running the Workflow
  • 4.4 Debugging
• 5. Credential Configuration
  • 5.1 Creating a GitHub App
  • 5.2 Installing a GitHub App
  • 5.3 Configure the Credential
• 6. Running MBT Tests
• 7. Limitations

3. Requirements

• At least one GitHub Actions runner allocated for running the integration.
• The recommended product version is 25.x or higher
• A Windows machine with OpenText Functional Testing (formerly UFT One) application installed
• API access to the product with CI/CD Integration or DevOps Admin roles.

4. Workflow Configuration

Note

These steps should be done inside your GitHub repository which contains the Functional Testing (formerly UFT One) tests.

• Create a new workflow (.yml file).
• Add workflow_dispatch event trigger to allow manual workflow run
• Add push event trigger to allow automatic workflow execution on every content change.

on:
  workflow_dispatch:
    inputs: 
	  # more details in the next NOTE
	  ...
  push:
    branches: main  # or other branches

Note

When the user will run a TestSuite, the OpenText SDP/SDM product will send a workflow_dispatch event to the GitHub workflow, with a payload containing 4 parameters. These parameters must be captured using 4 inputs, like these:

on:
  workflow_dispatch:
    inputs:
      testsToRun:
        description: 'Tests to run (from OpenText SDP/SDM)'
        required: true
        default: '...'
      suiteRunId:
        description: 'Suite Run Id (from OpenText SDP/SDM)'
        required: true
        default: '0'
      executionId:
        description: 'Execution Id (from OpenText SDP/SDM)'
        required: true
        default: '0'
      suiteId:
        description: 'Suite Id (from OpenText SDP/SDM)'
        required: true
        default: '0'

• If the product is configured on HTTPS with a self-signed certificate, configure node to allow requests to the server.

env: 
    NODE_TLS_REJECT_UNAUTHORIZED: 0

• In the jobs section add a job for github-action-ft-integration-mbt and make sure the runs-on property contains at least the self-hosted value.
• Configure two secret variables named SDP_CLIENT_ID and SDP_CLIENT_SECRET with the credentials, inside your GitHub repository (more details about secret variables configuration here).
• Set integration config params (the product's URL, Shared Space, Workspace, credentials) and repository (Token).
• For Private repositories go to Settings -> Actions -> General and set your GITHUB_TOKEN permissions to Read and write. This is necessary to access the actions scope. (more details about GITHUB_TOKEN permissions here)

jobs:
  ft_integration_job:
    runs-on: <runner_tags>
    name: GHA-FT-Integ-MBT#${{github.event.action}}#${{github.event.workflow_run.id}} # you can use a static / constant value too
    steps:
      - name: GitHub Action FT Integration MBT
        uses: opentext/github-action-ft-integration-mbt@main # you can use the last released version instead of main
        id: gha-ft-integration-mbt
        with:
          octaneUrl: <sdp_octane_URL>
          octaneSharedSpace: <sdp_shared_space_id>
          octaneWorkspace: <sdp_workspace_id>
          octaneClientId: ${{secrets.SDP_CLIENT_ID}}
          octaneClientSecret: ${{secrets.SDP_CLIENT_SECRET}}
          githubToken: ${{secrets.GITHUB_TOKEN}} # automatically generated by GitHub
          minSyncInterval: 2
          logLevel: 2

4.1. Full YML Example

Example of complete integration workflow configuration file:

name: GitHub-Action-FT-integ-MBT
on:
  workflow_dispatch:
    inputs:
      testsToRun:
        description: 'Tests to run (from OpenText SDP/SDM)'
        required: true
        default: '...'
      suiteRunId:
        description: 'Suite Run Id (from OpenText SDP/SDM)'
        required: true
        default: '0'
      executionId:
        description: 'Execution Id (from OpenText SDP/SDM)'
        required: true
        default: '0'
      suiteId:
        description: 'Suite Id (from OpenText SDP/SDM)'
        required: true
        default: '0'    
  push:
    branches:
      - main
permissions:
  actions: read  # Explicitly grant actions:read for this workflow
  contents: read  # Retain read access to contents if needed
env: 
    NODE_TLS_REJECT_UNAUTHORIZED: 0
jobs:
  ft_integration_job:
    runs-on: self-hosted
    name: Integration-Job
    steps:
      - name: GitHub Action FT Integration MBT
        uses: opentext/github-action-ft-integration-mbt@main 	# or use a release version instead of main
        id: gha-ft-integration
        with:
          octaneUrl: 'https://qa8.almoctane.com'
          octaneSharedSpace: 1001
          octaneWorkspace: 1003
          octaneClientId: ${{secrets.SDP_CLIENT_ID}}
          octaneClientSecret: ${{secrets.SDP_CLIENT_SECRET}}
          githubToken: ${{secrets.GITHUB_TOKEN}}
          minSyncInterval: 2
          logLevel: 5

• Run the desired workflow(s) from Actions Tab. This will create a new CI Server and Test Runner inside the product, reflecting the status of the executed workflow.

4.2 Workflow Parameters

Ensure the workflow includes these parameters:

• testsToRun (string)
• suiteId (number)
• suiteRunId (number)
• executionId (number)

For numeric parameters, set default to 0.

4.3 Running the Workflow

Run the desired workflow(s) from the Actions tab. This will create a new CI Server and Test Runner inside the product, reflecting the status of the executed workflow.

4.4. Debugging

• In order to get more information on the execution of the integration workflow, add this parameter for the integration job: logLevel: '3'.
• These are the available values for this parameter:
  • 1 - trace level
  • 2 - debug level
  • 3 - info level
  • 4 - warning level
  • 5 - error level

5. Credential Configuration into the product

• To use certain features, the product needs to send requests to GitHub. This requires configuring a GitHub App credential and adding it to the application.

5.1. Creating a GitHub App

1. On GitHub, go to your organization (or account, if the repository containing the workflows is owned by an account) settings.
2. In the left-side menu, go to Developer Settings -> GitHub Apps.
3. Create a new GitHub App by clicking on New GitHub App.
4. In the GitHub App name field, enter a name of your choice.
5. In the Homepage URL field, enter the URL of the Opentext Software Delivery Platform.
6. In the Webhook section, uncheck the Active option. No webhook is needed.
7. In the Permissions section, grant the following repository permissions:

• Actions: Read and write
• Content: Read-only

8. Click on the Create GitHub App button at the bottom of the page. Leave any other fields unchanged.

5.2. Installing a GitHub App to specific repositories

1. On GitHub, go to your organization (or account, if the repository containing the workflows is owned by an account) settings.
2. Go to Developer settings -> GitHub App.
3. Select the credential you created in the previous step by clicking on its name.
4. In the left-side menu, go to Install App.
5. For the organization (or account) you want to configure the credential for, click on the Install button.
6. Select the repositories you want to grant access to: All repositories or Only select repositories
7. Click on the Install button to complete the installation.

5.3. Configure the credentials into the product

1. On GitHub, go to your organization (or account, if the repository containing the workflows is owned by an account) settings.
2. Go to Developer Settings -> GitHub Apps and select the GitHub App you installed by clicking on its name.
3. On the current page, note the value of the Client ID.
4. In the Private keys section, click on Generate a private key. A file containing the private key will be downloaded to your device.
5. Go to the OpenText Software Delivery Platform.
6. Navigate to Settings -> Spaces (select the desired workspace containing the CI servers) -> Credentials.
7. Create a new credential.
8. Enter a name of your choice. In the User Name field, enter the Client ID from the GitHub App, and in the Password field, enter the private key generated for this GitHub App.
9. Click on the Add button to create the credential.
10. In workspace settings, go to DevOps -> CI Servers.
11. For the desired CI server (it has the name of the organization on GitHub), double-click on the cell in the Credential column and select the newly created credential. If the Credential column is not visible, click on the Choose Columns button (near the Filter button) and make the column visible.

6. Running MBT Tests from the product

1. Configure Workflow Parameters:

   • Ensure the parameters required for automated tests are properly set up in the YML workflow as described earlier.
   • The workflow must include the following parameters:
     • testsToRun (type: string)
     • suiteId (type: number)
     • suiteRunId (type: number)
     • executionId (type: number)
   • For numerical parameters, it is recommended to set a default value of 0.

2. Run the Workflow:

   • After completing the configuration, run your workflow.
     • The CI Server and Test Runner entities will be automatically created in the product
     • The Test Discovery and Synchronization mechanisms will be triggered, so that all FT tests' Actions from current repo will be collected and injected as Units in the product.

• Example of Credential entity created at step 5.3 Configure the Credential:

• Make sure a Release entity exists, otherwise create it (required to Run a Test Suite):

• Make sure the CI Server is using the appropriate the Credential entity:

• Select the Test Runner and click Sync with CI:

• Optionally, review the Test Runner details:

3. Create Models and MBT Tests:

   • In the product, navigate to the Model-Based Testing module, create a new Model entity, add the desired Units and link them
   • Example of Model entity:

• To generate the MBT Test entities, open the Paths tab, select the desired items, then click Generate Test:

• After generating the MBT Test, the column Covered by test should be populated like this:

4. Create a Test Suite:

   • Open the Execution or Quality module and go to Tests tab:

• Create a Test Suite entity if you don't have one, then assign the relevant MBT Test entries to it.

• Make sure the Run Mode is set to Automatic, and update Test Suite like this:

5. Run the MBT Tests from the Product:
   • In the product, select or open the test suite and click Run, respectively Run Suite.

7. Limitations

• One self-hosted GitHub runner to execute the integration workflow.