Table of Contents

• Getting Started
  • Helpful Background Information
  • Prerequisites
  • External Dependencies
  • Adapters
  • How to Install
  • Testing
• Using this Workflow Project
  • Prebuilt Promotion Azure DevOps
• Additional Information
  • Support

Getting Started

This section is helpful for deployments as it provides you with pertinent information on prerequisites and properties.

Helpful Background Information

Workflows often include logic that varies from business to business. As a result, we often find that our Workflow Projects are more useful as modular components that can be incorporated into a larger process. In addition, they often can add value as a learning tool on how we integrate with other systems and how we do things within the Itential Automation Platform.

While these can be utilized, you may find more value in using them as a starting point to build around.

Prerequisites

Itential Workflow Projects are built and tested on particular versions of IAP. In addition, Workflow Projects are often dependent on external systems and as such, these Workflow Projects will have dependencies on these other systems. This version of Prebuilt Promotion Azure DevOps has been tested with:

• IAP 2023.2

External Dependencies

Adapters

How to Install

To install the Workflow Project:

• Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Supported IAP Versions section in order to install the Example Project.
• Import the Example Project in Admin Essentials.

Testing

Cypress is generally used to test all Itential Example Projects. While Cypress is an opensource tool, at Itential we have internal libraries that have been built around Cypress to allow us to test with a deployed IAP.

When certifying our Example Projects for a release of IAP we run these tests against the particular version of IAP and create a release branch in GitLab. If you do not see the Example Project available in your version of IAP please contact Itential.

While Itential tests this Example Project and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this Example Project into a development/testing environment in which you can test the Example Project.

Using this Workflow Project

Workflow Projects contain 1 or more workflows. Each of these workflows have different inputs and outputs.

Prebuilt Promotion Azure DevOps

Prebuilt Promotion Azure DevOps takes a prebuilt installed on IAP in Admin Essentials and creates a new repository or updates an existing repository by way of a pull request in Azure DevOps. This repository contains the prebuilt's IAP components as well as script and pipeline files to verify the prebuilt's artifact.json file is generated correctly, increments the prebuilt version, updates CHANGELOG of changes made to the prebuilt, and optionally promotes the prebuilt to another IAP environment.

Capabilities include:

• Create a new repository or update an existing repository by way of a pull request in Azure DevOps for a Prebuilt as found on the local IAP where Prebuilt Promotion Azure DevOps is being run.
• Include the necessary configuration files and scripts to run a CI/CD pipeline if running Prebuilt Promotion Azure DevOps against a repository that does not exist in Azure DevOps.
• Optionally promote the the Prebuilt generated in Azure DevOps by CI/CD pipeline to a higher environment IAP instance once changes to Prebuilt are reviewed, tested, and approved for higher environment instance.

Configuring Dependencies

Azure DevOps

Prior to running this prebuilt, Azure DevOps must be set up properly according to the following:

• An organization must be created in Azure DevOps.
• A project must be created in the organization made in the step above.
• The Azure DevOps project settings must be configured in order to provide proper authorization for creating and updating repositories.
  To configure these settings in the Azure DevOps user interface (UI), navigate to the created project in the Azure DevOps UI. Click on the navigation element Project settings on the bottom-left corner of the UI. From within Project settings, click on side navigation item Repositories listed under Repos. From this page, click on the tab Security at the top of the page listed under All Repositories.
  With the Security tab selected, verify the Users {project_name} Build Service ({organization_name}) and Project Collection Build Service ({org_name or ID}) have the following roles set to allow:
  • Contribute
  • Contribute to pull requests
  • Create branch
  • Create repository
  • Create tag
  • Read

Azure DevOps CI/CD Variables

In order to run the Promote stage of the CI/CD pipeline, a variable group must be created within the project with the following name: IAP Variables.
To create a variable group in the Azure DevOps user interface (UI), navigate to the created project in the UI. Click on the Pipelines item in the left-hand side navigation panel to expand options for pipelines and click on Library to be directed to the Library settings. On Library UI, click on the tab + Variable group at the top of the Library page and enter IAP Variables as the Variable Group Name. For more information on creating a variable group, see the Azure DevOps documentation here.
The following variables need to be set in the variable group:

• PROMOTE: This variable determines if the Promote stage of the pipeline will run. Example values: True or False. Only when this value is assigned True will the Promote stage be run. If any over value is assigned, or the variable is not defined, the Promote stage will not run or attempt to import artifact.json to target IAP.

• IAP_HOSTNAME: This variable determines the target IAP to attempt to import the auto-generated artifact.json to. Example value: https://ACME.itential.com

• IAP_TOKEN: This variable is required if using token authentication and not basic authentication to attempt to use the IAP Pre-Built import API to import the artifact.json to the target IAP. Recommend this variable type be set to secret in Azure DevOps. Example value: 123_sample_token

• IAP_USERNAME: This variable is required if using basic authentication to attempt to use the IAP Pre-Built import API to import the artifact.json to the target IAP. Recommend this variable type be set to secret in Azure DevOps. Example value: iap_user@domain.com

• IAP_PW: This variable is required if using basic authentication to attempt to use the IAP Pre-Built import API to import the artifact.json to the target IAP. Recommend this variable type be set to secret in Azure DevOps. Example value: my_password_123

• IAP_SSL_CERT: This variable is required if using two-way SSL verification for HTTPS for target IAP attempt to use the IAP Pre-Built import API to import the artifact.json to the target IAP. Note if using Cloud IAP, this value can be created by copying from the web browser the IAP server certificate, intermediate certificate, and root certificate to a single file, in that order. Recommend this variable type be set to secret in Azure DevOps. Example value:
  

    -----BEGIN CERTIFICATE-----
    <server certificate>
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    <intermediate certificate>
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    <root certificate>
    -----END CERTIFICATE-----

• IAP_SSL_CERT_FILE_NAME: This variable is required if needing to use SSL verification but the certificate content exceeds 4096 characters. The value assigned to this variable must equal the name of a secure file created in Azure DevOps that has the certificate. Note if using this setup, the pipeline content as found in azure-pipelines-secure-file.yml here must be used instead of the default azure-pipelines.yml file. Additionally, the promote.py file content must be updated to be what is found in promote-secure-file.py here. Refer to section CI/CD Pipeline Stages of this README to see how to update Prebuilt Promotion Azure DevOps to have modified pipeline or script content as compared to the default values.

CI/CD Pipeline Stages

On running Prebuilt Promotion Azure DevOps against a target repository that does not yet exist in Azure DevOps, Prebuilt Promotion Azure DevOps initializes the repository with CI/CD script and pipeline files. Below describes the stages of the CI/CD process setup:

• Security: This step ensures that there are no security vulnerabilities in the npm package dependencies of the repository.

• UnitTest: Validates path links when comparing artifact.json to manifest.json as well as validates manifest.json against its JSON schema definition. This stage is implemented by jobs SchemaValidation for verifying manifest.json and SchemaLinksValidation for verifying artifact.json against manifest.json.

• GenerateArtifactPullRequest: Creates artifact.json from bundles directory and manifest.json file in repository and commits that file to the candidate branch. This stage is only run on commit to the candidate branch of a pull request.

• GenerateArtifactVersionBump: Increases the version of the prebuilt based on the candidate branch name prefix being set to patch, minor, or major, following semver. If no prefix is found in the branch name, the default semver value is patch. Additionally, this stage updates the repository CHANGELOG.md with commit changes or pull request information as well as generates a new artifact.json and commits these files to the main branch.

• Promote: This stage attempts to import the updated artifact.json to a target IAP instance using the CI/CD variables configured. Note that this stage is only run on commit to the main branch in Azure DevOps. Changes to the pipeline file are necessary if there is need to run this stage on commit to a candidate branch of a pull request.

By default, Prebuilt Promotion Azure DevOps uses the Azure DevOps cloud deployment version of the pipeline file as found in the Itential Open Source common-utils repository here. If using an Azure DevOps on-premise deployment, the pipeline file can be updated in IAP Transformation Azure DevOps Set Pipeline Script Files. In particular, the function setPipelineScriptsFileContent in that Transformation will need to be updated with the on-premise version of the pipeline as found here if needing to use that version in Azure DevOps. You may need to modify this pipeline file or other script files further to suit your on-premise environemnt.

App-Artifacts

App-Artifacts has to be installed on IAP to be able to run Prebuilt Promotion Azure DevOps. If you do not currently have App-Artifacts installed, the .tgz tarball file can be obtained from the Nexus repository. This webpage requires an active account with Itential. After downloading the latest App-Artifacts app, please refer to the instructions included in the App-Artifacts README for how to install it on IAP. Please use your Itential Customer Success account if you need support accessing Nexus or installing App-Artifacts.

Entry Point IAP Component

The primary IAP component to run Prebuilt Promotion Azure DevOps is listed below:

Inputs

The following table lists the inputs for Prebuilt Promotion Azure DevOps:

Prebuilt Organization

Prebuilt Project

Prebuilt Repository

@prebuilts/my-prebuilt

7.0

azure_devops

{
  "mrType": "patch",
  "commitMessage": "Update components",
  "targetBranch": "main"
}

false

{
  "verbose": false
}

Outputs

The following table lists the outputs for Prebuilt Promotion Azure DevOps:

SUCCESS

Query Output

The following items show how to query successful results from the output of Prebuilt Promotion Azure DevOps:

Prebuilt Promotion Azure DevOps Result

ReturnStatus

Example Inputs and Outputs

Example 1

Input:

{
  "formData": {
    "options": {
      "verbose": false
    },
    "reDiscoverPrebuilt": false,
    "commitDetails": {
      "mrType": "patch",
      "commitMessage": "Adds workflow",
      "targetBranch": "main"
    },
    "organizationName": "Prebuilts Organization",
    "projectName": "Prebuilts Project",
    "repository": "Prebuilt Repository",
    "prebuilt": "@prebuilts/my-prebuilt",
    "azureAdapter": "azuredevops",
    "apiVersion": "7.0"
  }
} 

Output:

{
  "ReturnStatus": "SUCCESS"
} 

API Links

Additional Information

Support

Please use your Itential Customer Success account if you need support when using this Workflow Project.

Itential Documents:

Related Items:

Adapters