@itentialopensource/prebuilt-promotion-azure-devop

Prebuilt Promotion Azure DevOps

Prebuilt Promotion Azure DevOps

Overview

The Prebuilt Promotion Azure DevOps Pre-Built is used to push a Pre-Built directly to an Azure DevOps project, or make an update to an existing Pre-Built in Azure DevOps. It is also used to promote the new Pre-Built directly towards a specified instance of IAP (staging/prod/etc.).

Estimated Run Time: <5 minutes, depending on prebuilt complexity

Supported IAP Versions

Itential Pre-Builts are built and tested on particular versions of IAP. Please make sure to run on the following version:

Itential Automation Platform
- ^2023.1

Getting Started

These instructions will help you get a copy of the Pre-Built in your IAP instance for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.

Prerequisites

This Pre-Built requires the following:

adapter-azure_devops
- v0.1.11
App-Artifacts
- ^6.5.3-2023.1.1

If you do not currently have App-Artifacts installed as a service on your IAP, the .tgz file or "tarball" can be obtained from the Nexus registry. Please refer to the instructions included in the App-Artifacts README to install it.

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

An organization must be created in Azure DevOps.
A project in the organization above must be created. This is where the repositories will be stored.
In order to grant proper authorization for creating and updating repositories, the Azure DevOps project settings must be updated before running this Pre-Built:
- In the Azure DevOps UI at the bottom left of the Project screen click the button: Project settings, followed by Repositories then Security:
  - Verify the Azure DevOps 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
A variable group under the desired project with the following name: IAP Credentials. This can be found in the Azure DevOps UI on the Projects page follwed by the Pipeline tab then under the Library button
- Must have IAP_HOSTNAME defined (e.x. https://your-itential-url)
- Either an IAP_TOKEN defined (secret or non-secret) or BOTH IAP_USERNAME and IAP_PW
- If using two-way SSL verification for HTTPS for target IAP promotion, IAP_SSL_CERT must be defined as
```
-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----
```
- Under the tab 'Pipeline Permissions', it must be set to open access/no-restrictions (see 3 dots from option)
A Personal Access Token (found under User Settings on the top right in the Azure DevOps UI next to your account icon) is configured for your organization (or all organizations) with full access.

Furthermore, an azuredevops adapter should be installed into your dev IAP with example service config shown below: _Note the attempt-timeout value should be set to atleast 15000 for all IAP instances

Under properties.properties:
- "host" : "dev.azure.com"
- "base_path" : "/"
- "protocol" : "https"
Under properties.properties.authentication:
- "auth_method": "basic user_password"
- "username": "***your-email***"
- "password": "***Personal-Access-Token (from above)***"
- "token": "token"
- "token_timeout": 600000
- "token_cache": "local"
- "invalid_token_error": 401
- "auth_field": "header.headers.Authorization"
- "auth_field_format": "Basic {b64}{username}:{password}{/b64}"
Under properties.properties.request:
- "attempt_timeout" : 15000

Capabilities

Pushes IAP components as well as scripts for CI/CD pipeline of a Pre-Built found on IAP in Admin Essentials to targeted Azure DevOps repository
In the case of no existing repo:
- Workflow creates a new repository with provided name
- Adds standard script and test files to repo
- Adds Bundles folder and Manifest.json to repo
- Creates and starts a new Pipeline for the repo
In the case of pre-existing repo:
- Workflow creates a new branch with name {MR Type}/{Date&Time}
- Deletes Bundles folder and Manifest.json
- Commites new Bundles and Manifest.json (from updated Pre-Built)
- Creates a Pull Request with title: Merge Branch '{source_branch}' into '{target_branch}'
In the Azure DevOps environment:
- A Pipeline is kicked off which runs the QUALITY_TESTING and GENERATE stage for all branches, and VERSION_BUMP and PROMOTE stage on the main/release branches
- The PROMOTE stage imports the Pre-Built into the staging IAP environment

How to Install

To install this Pre-Built:

Verify that you are running the documented prerequisites in order to install the Pre-Built.
Follow the instructions on the Itential Documentation site for importing a Pre-Built.

Testing

While Itential tests this Pre-Built 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 Pre-Built into a development/testing environment in which you can test the Pre-Built.

Using this Pre-Built

This Pre-Built should be run in an automation.

Note: The entry Operations Manager automation to this Pre-Built is called Prebuilt Promotion Azure DevOps.

There are differences in the pipeline file for an on-premise Azure DevOps deployment compared to a cloud deployment. By default, Prebuilt Promotion Azure DevOps uses the cloud version of the pipeline file as found here.

If using an on-premise deployment, see description of input useItentialScriptFiles in table below for updating Transformation included in this Pre-Built Azure DevOps Get Custom Script Files to set pipeline file statically to be the on-premise version as found here. You may need to modify this pipeline file or other script files further to suit your on-premise environemnt.

When running this Pre-Built, it depends on being provided proper input so that Azure DevOps can recieve commits and commit details as expected. The input to and possible outputs from this Pre-Built are described below

Input Schema

Example input to the trigger form:

{
  "formData": {
    "options": {
      "verbose": false
    },
    "reDiscoverPrebuilt": false,
    "commitDetails": {
      "commitMessage" : "Init",
      "mrType" : "patch",
      "targetBranch": "main"
    },
    "azureAdapter" : "azure_devops",
    "organizationName": "{organization_name}",
    "projectName": "{project_name}",
    "repository": "{repository_name}",
    "prebuilt": "@local/pre-built-name",
    "apiVersion" : "7.0",
    "useItentialScriptFiles": "true"
  }
}

The following table details the property keys of the input object. | key | type | required | description | |------------------------------------------|---------|----------|---------------------------------------------------------| | azureAdapter | string | yes | Name of the Azure DevOps adapter for API calls | | options.verbose | bool | no | Makes the Workflow run in Verbose mode (extra details) | | reDiscoverPrebuilt | bool | no | Grabs new or deleted components from Pre-Built | | commitDetails | object | no | Add specific Commit Details | | commitDetails.commitMessage | string | no | Commit Message for commits to Azure DevOps (Not in Use) | | commitDetails.mrType | string | no | Merge Request Type (patch, minor, or major) | | commitDetails.targetBranch | string | no | Target Branch for the Merge Request | | organizationName | string | yes | Name of Organization in Azure DevOps | | projectName | string | yes | Name of Project in Azure DevOps | | repository | string | yes | Name of Repository in Azure DevOps | | prebuilt | string | yes | Name of Prebuilt to promote to Azure DevOps and Staging IAP | | apiVersion | string | no | Version of API to run REST calls with (default is 7.0) | | useItentialScriptFiles | string | yes | If creating a new repository for a Pre-Built, set to "true" to populate the repository with the Itential Open Source pipeline script files as found here. Set to "false" to use the customizable script files as set in the Transformation Azure DevOps Get Custom Script Files in the new Azure DevOps repository. This value is ignored for creating pull requests against existing repositories. |

Output Schema

The ReturnStatus job variable returned from the run Pre-Built workflow Prebuilt Promotion Azure DevOps reports the success or failure of promoting the Pre-Built to Azure DevOps.

Example output for creating repo (SUCCESS):

{
  "ReturnStatus" : {
    "project": "{project_name}",
    "organization": "{organization_name}",
    "options": {
      "verbose": "false"
    },
    "repository_id": "{repository_name}",
    "message": "Successfully create a new Repo with main branch and Successfully pushed pipeline files to repo and Successfully started the pipeline",
    "errors": [],
    "status": "SUCCESS",
    "response": [
      {
        "create_repo": {},
        "create_main_branch": {}
      },
      {
        "push_script_files": {},
        "get_file_contents": []
      },
      {
        "run_pipeline": {},
        "create_pipeline": {}
      }
    ]
  }
}

Example output for updating repo (SUCCESS):

{
  "ReturnStatus": {
   "project": "{project_name}",
    "organization": "{organization_name}",
    "options": {
      "verbose": "false"
    },
    "repository_id": "{repository_name}",
    "message": "Successfully created new branch from default branch and Successfully committed changes to Azure DevOps and Successfully committed file(s) to Azure DevOps repository and Successfully Created a Pull Request and Successfully started the pipeline",
    "errors": [],
    "status": "SUCCESS",
    "response": [
      {
        "create_new_branch": {},
        "get_branches": {}
      },
      {
        "delete_bundles_manifest": {},
        "get_bundles_manifest_paths": {}
      },
      {
        "add_bundles_manifest": {}
      },
      {
        "pull_request": {}
      },
      {
        "run_pipeline": {},
        "create_pipeline": {}
      }
    ]
  }
}

Example output for FAILED:

{
  "ReturnStatus": {
    "project": "{project_name}",
    "organization": "{organization_name}",
    "options": {
      "verbose": "false"
    },
    "repository_id": "{repository_name}",
    "message": "Failed to create a new repo with main branch and Did not run 'Run Pipeline' child job",
    "errors": [
      {
        "message": "Failed to create new repository",
        "error_details": {}
      },
      {
        "message": "Failed To Create Master Branch",
        "error_details": "Workflow failed before branch creation."
      }
    ],
    "status": "FAILED",
    "response": [
      {
        "create_repo": {},
        "create_main_branch": "Workflow failed before branch creation."
      },
      {
        "create_pipeline": "Did not run 'Create Pipeline' child job",
        "run_pipeline": "Did not run 'Run Pipeline' child job"
      }
    ]
  }
}

The following table details the property keys of the output ReturnStatus object. | key | type | description | |------------------------------------------|---------|--------------------------------------------------------------------| | status | enum | The status of the whole workflow (SUCCESS or FAILED) | | message | string | A message saying which tasks completed and their status | | options.verbose | bool | Makes the Workflow run in Verbose mode (extra details) | | organization | string | Name of Organization in Azure DevOps | | project | string | Name of Project in Azure DevOps | | repository_id | string | Name of Repository in Azure DevOps | | response | array | An array consisting of objects which correspond to child workflows | | errors | array | An array of errors that occured during the prebuilt promotion run |