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 enable your GitHub repository to trigger MBT test runs and synchronize results with OpenText SDP/SDM.

2. Table of Contents

• 1. Introduction
• 2. Table of Contents
• 3. Requirements
• 4. GitHub Workflow Setup
  • 4.1. Workflow creation
  • 4.2. Full YML Example
  • 4.3. Workflow Parameters
  • 4.4. Debugging
• 5. Credentials Configuration
  • 5.1. Creating a GitHub App
  • 5.2. Installing a GitHub App
  • 5.3. Configure the Credentials in the product
• 6. Running MBT Tests
  • 6.1. GitHub self-hosted runner
  • 6.2. Run the Workflow for the first time
  • 6.3. Create Models and MBT Tests
  • 6.4. Create a Test Suite
  • 6.5. Run the MBT Tests from the Product
• 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.
• Within a single workspace, you can only have one MBT Test Runner associated with each GitHub repository. Therefore, before setting up the custom action to run MBT tests from a specific repository, make sure no existing MBT Test Runner in the same workspace is assigned to the same repository.

4. GitHub Workflow Setup

This section explains how to create and configure a GitHub Actions workflow that integrates OpenText Functional Testing with Model-Based Testing (MBT).

4.1. Workflow creation

Note

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

• Create a new workflow from GitHub Actions tab (resulting in a new .yml file inside of <your_repo>/.github/workflows/ subfolder).
• Add workflow_dispatch event trigger to allow manual workflow run
• Add push event trigger to allow automatic workflow run on every content change.

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

• Under inputs section, 4 input parameters must be added (see next example).

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'

Note

When the user will run a TestSuite from product, the product will automatically send a workflow_dispatch event to the GitHub workflow, with a payload containing the 4 parameters and values. Even if the user manully runs the workflow from GitHub Actions, the default value of these 4 parameters must not be changed by user.

• 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 sdp-ft-mbt-github-action-integration 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/sdp-ft-mbt-github-action-integration@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: 5

For more details about the parameters of opentext/sdp-ft-mbt-github-action-integration, please check this page: https://github.com/MicroFocus/sdp-ft-mbt-github-action-integration/blob/main/action.yml

4.2. 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/sdp-ft-mbt-github-action-integration@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.3. Workflow Parameters

Ensure the workflow includes the 4 required parameters:

• testsToRun (default: '...')
• suiteId (default: '0')
• suiteRunId (default: '0')
• executionId (default: '0')

Note

When the user will run a TestSuite from product, the product will automatically send a workflow_dispatch event to the GitHub workflow, with a payload containing 4 parameters and values. Even if the user manully runs the workflow from GitHub Actions, the default value of these 4 parameters must not be changed by user.

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 (default)
  • 4 - warning level
  • 5 - error level

5. Credentials Configuration

To use certain features, the product needs to send requests to GitHub. This requires configuring GitHub App credentials and adding them 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 the 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 Core 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 the Create GitHub App button at the bottom of the page. Leave any other fields unchanged.

5.2. Installing 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. Go to Developer settings -> GitHub Apps.
3. Select the GitHub App you created in the previous step by clicking its name.
4. In the left-side menu, go to Install App.
5. For the organization (or account) you want to configure the credentials for, click the Install button.
6. Select the repositories you want to grant access to: All repositories or Only select repositories
7. Click the Install button to complete the installation.

5.3. Configure the credentials in 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 its name.
3. On the current page, note the value of the Client ID.
4. In the Private keys section, click the Generate a private key button. A file containing the Private Key will be downloaded to your device (usually this is a .pem file). Note: Private Keyshould not be confused with Client secret (which is not required / used).
5. Go to the OpenText Core Software Delivery Platform.
6. Navigate to Settings -> Spaces (select the desired workspace containing the CI servers) -> Credentials.
7. Create a new Credentials entity.
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 (the full content from .pem file) generated for this GitHub App.
9. Click the Add button to save the credentials.
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 the cell in the Credential column and select the newly created entity. If the Credential column is not visible, click the Choose Columns button (near the Filter button) and make the column visible.

6. Running MBT Tests

6.1. GitHub self-hosted runner

• After completing the configuration, make sure the desired GitHub self-hosted runner is active, from GitHub Settings -> Actions -> Runners
• To set up a GitHub self-hosted runner, follow the instructions provided in GitHub's documentation:
  1. Visit the Adding self-hosted runners guide: https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/add-runners
  2. Understand the prerequisites and select the machine you will use for your self-hosted runner.
  3. Follow the steps to add a self-hosted runner at the repository, organization, or enterprise level.
• If you'd like to learn more about self-hosted runners, their configuration, and management, see the following resources:
  • Managing self-hosted runners: https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners
  • About self-hosted runners: https://docs.github.com/en/actions/concepts/runners/self-hosted-runners

6.2. Run the Workflow for the first time

• After completing the configuration, run your workflow once, manually, from GitHub Actions tab.

  • 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.

• You can manually rerun the Workflow anytime, or it will be automatically triggered by push events.

  • Then, the Test Discovery and Synchronization mechanisms will be triggered again (if the minSyncInterval minutes has elapsed since the last sync).

• Example of Credentials entity created at step 5.3. Configure the Credentials in the product:

• 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 Credentials entity:

• Select the Test Runner and click Sync with CI:

• Optionally, review the Test Runner details:

6.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:

6.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 Automatically, and update Test Suite like this:

6.5. Run the MBT Tests from the Product

• In the product, select or open the test suite and click Run Suite.

7. Limitations

1. One self-hosted GitHub runner is required to execute the integration workflow.
2. Within a single workspace, you can only have one MBT Test Runner associated with each GitHub repository. Since the MBT Test Runner creation depends on the YML workflow you use, make sure to create only one YML workflow per GitHub repository. An attempt to sync a second branch (using a second YML workflow) will fail.