Building and Releasing

Pipelines are typically under your team's Azure DevOps Project but if your team doesn't have a project set up, you can add the pipeline into the Azure DevOps Hub Project.

Common resources used for pipeline configuration are located in azure-devops.

Building and Releasing in your own Azure DevOps Project

If this is the first time you are setting up a build/release pipeline for Hub v1 or a Hub React app in your Azure DevOps Project, you will need to configure the project first.

Azure DevOps Pipelines#

Creation#

The pipeline will be used to create an artifact containing the bundled version of your application and deploy it across all environments. To get started, you can extend the common pipeline template, but custom steps can get added to meet your needs.

  1. Create the following azure-pipelines.yml file in the root of your repository to extend the build pipeline template provided by azure-devops.

    # See documentation for reference
    # https://design-system.iqmetrix.net/docs/web-dev/guides/building-and-releasing
    # A reference to frontend-packages to access the pipeline template
    resources:
    repositories:
    - repository: frontend-packages
    name: iqmetrix/frontend-packages
    type: github
    endpoint: GitHub-iQmetrixService
    trigger:
    - master # The branch to automatically trigger builds when updated
    stages:
    - template: packages/utilities/azure-devops/stages.yml@frontend-packages
    parameters: # Optional definition (used mostly for Hub v1 apps)
    build:
    hubVersion: 1 # You can 1 for Hub v1 apps and 3 for React apps. When not defined, it will assume 3 as default
    Defining PR build validation

    For Azure Repositories, you need to set up branch policies to trigger a build on each PR to validate it. For GitHub Repositories, you need to set up webhooks and branch protection rules.

  2. Set the homepage property in your package.json to the directory your application will be served from.

    Your application will fail to build in Azure Devops without this set

    DONT FORGET THE LEADING SLASH, must be a relative path or your app will fail to be loaded.

    {
    ...
    "homepage": "/<my-app>",
    ...[
    }
  3. Go to iQmetrix / Your Project / Pipelines and select New Pipeline.

    • Connect: Select GitHub
    • Select: Select your repository
    • Configure: Your azure-pipelines.yml file should be detected automatically. If not, select Existing Azure Pipelines YAML file and azure-pipelines.yml
    • Review: Press Save and run

Usage#

We recommend following SemVer for versioning your applications. The version property from package.json is automatically included in the /ping file at build time.

  1. Go to iQmetrix / Your Project / Pipelines and select your app.

  2. Deploy to Integration

    If you set up the trigger in your pipeline, this will occur automatically with a commit to master

    1. Select: Run pipeline
    2. Choose your branch
    3. Select: Run
    4. Your app build will run and, once complete, will deploy to Integration.
  3. Promote to further environments

    Make sure you follow all Change Management protocols when releasing beyond Int. See Change Management section down below.

    1. Select the build you would like to promote
    2. Under the environment you would like to deploy to, select 0/1 checks passed
    3. Approve the check

      If you are unable to approve the check, ensure you have the permission to do so.

    4. The deploy will run, and once complete, your app will be live.

Change Management#

All Production, RC, and Demo environment changes need to go through the Change Management team. Official documentation can be found on the Change management wiki.

Step by Step#

  1. Inform Change Management team (CM) about your deployment using the Change Management Form (this is only accessible through the VPN).

    You will receive a confirmation from the CM team before you can deploy, with the specified, or alternative, time.

  2. Deploy your app.

    • See Usage for newer apps.

    • If you are deploying a Hub v2 app, go to TeamCity:

      • Locate the app you want to deploy

      • Hit the run button to deploy to the desired environment on the specified time.

        If you are not deploying the latest build, you have to click the ... button next to run button and select the right build.

  3. Post in the slack channel #changemanagement when the change is started, ended, and completion status.

    This is not necessary for Hub.app (shell) - there is an automatic message.

  4. Update your CM ticket (link to the ticket will be in the confirmation email you'll receive)

Example Change Management Request#

Change Details#

  • Change Name: Release app@version to environment
  • Client(s): Who uses your app?
  • Description: What is included in this release?
  • Specialty Change Type: N/A
  • Client Impact: What will this change do for your clients?
  • Is Downtime Required: No
  • Change Type: Scheduled
  • Approver: Usually your tech lead
  • Requested Change Date and Time (CST Timezone): MM/DD/UUU hh:mm am/pm
  • Duration (Hour:Minutes) hh:mm (usually 00:15
  • Risk: Low / Medium / High
  • Scope: environment

Testing#

  • Do you have Test Evidence? Yes
  • Describe the tests performed and results:
    • What did you do to confirm this release is working?

Cricket#

  • Does this change require Cricket Approval?: Yes if this affects Cricket

Implementation Team#

  • Deployment team(s): Your team or a team doing this for you
  • Deployment team(s) ticket required: Yes if another team
  • Validation Team: Who is making sure this works after release?
  • Contingency Plan: Revert to previous build version
  • Contingency Steps:
    1. link to release site (TeamCity or Azure DevOps)
    2. What do you need to do on that page?

PCI Changes#

  • Will this change be affecting Network configurations?: No
  • Will this change involve an addition or replacement of a network device?: No

Release Notes#

To provide our clients with the best experience, releases of Hub Apps to production with client-facing changes require release notes submitted to our Knowledge Base. Release notes provide transparency and highlight the progress we're all making in Hub.

Bugs and other fixes are not included within Hub Release Notes at this time. Technical Support follows support tickets, updating applicable clients when the issue is fixed.

For further questions around Hub Release Notes, reach out in #knowledge_management.

Process#

  1. When a client-facing change to Hub occurs (I.E. UI, feature/functionality update/addition/removal), Hub teams, usually your product owner, will email Knowledge Management (SupportCommunity@iqmetrix.zendesk.com) with details about the change.
  2. Change Management will forward CM tickets for production Hub app changes to KM as a redundancy check.

Template#

---
to: [SupportCommunity@iqmetrix.zendesk.com](mailto:SupportCommunity@iqmetrix.zendesk.com)
subject: Release Notes - APP_NAME@VERSION DATE_OF_RELEASE
---
[CM Ticket](link_to_cm_ticket)
- [Work Item 1](link_to_work_item) - Short client-facing description
What: Change details including before and after and images
Why: Why we made the change
Additional Notes: Any other important notes

Tips#

Descriptions#

  • Most details should already be included in your Change Management tickets and can just be shared.

Before and After Images#

  • Full-page screenshots
  • Don't include sensitive or personal information
  • Don't include additional image markings such as cursors or highlighting

Configuring your Azure DevOps Project#

Follow these steps below to configure your pipelines under your project. You just need to do it once and it will be available to any further pipeline.

Service Connections#

The first step is to have all the necessary service connections configured under your project settings.

GitHub-iQmetrixService#

All projects should now have the connection GitHub-iQmetrixService. If yours does not, request their additions in #azure-devops.

SharedMicroservices-Development and SharedMicroservices-Production#

  1. Open your Azure DevOps project

  2. In the sidebar, at the bottom, click on the Project settings

  3. Now, go to the menu Service connections

  4. Create a new service connection for SharedMicroservices-Development and SharedMicroservices-Production

    If you do not have permissions to create these service connections, request them from cloudops@iqmetrix.com

    1. Create a New service connection of type Azure Resource Manager
    2. Select Service principal (automatic)
    3. Set Subscription according to the subscription you are connecting to
    4. Set Service connection name to SharedMicroservices-Development or SharedMicroservices-Production
    5. Save

BuildAndDeploySharedResources resource group#

Refer to the Create and manage a Service Connection - Shared connections to Azure subscriptions and other resources`

Environments#

In order to defer your releases to later environments until manual approval is granted, you must add approvals.

  1. Open your Azure DevOps project
  2. In the sidebar, under Pipelines, select Environments
  3. Create all required environments with no resources
    • Int
    • RC
    • Demo
    • Prod
  4. For each environment that you want to require a manual approval prior to releasing:
    1. Select the environment in the list
    2. Select Approvals and checks
    3. Select Approvals
    4. Add your team as an approver for the environment

Azure Key Vault Access Policy#

If you do not have the permissions to access the SharedMicroservices-Development subscription in Azure, you may request the creation of this access policy in #hub-developers.

  1. Navigate to the hub-build Azure Key Vault Access Policies
  2. Add Access Policy
  3. Under Select principal, select the principal associated with your previous created service connection to SharedMicroservices-Development
  4. Under Secret permissions select Get and List
  5. Add
  6. Save

Hub v1 and Azure DevOps#

You can now deploy Hub v1 applications using Azure DevOps Pipelines, following the same steps as described above.

These steps are available only if you are using HubCommon@5.x.x and Hub.Common.Tooling@^2.7.1.

About Hub v1 cache

Note that Azure Pipelines use your package.json version to generate the RequireJS cache, while TeamCity used the build number for the same purpose. Make sure that you are following the SemVer for your app.

  1. Follow the same steps as described in the Pipeline - Creation.

    Don't forget to add your homepage setting as defined in your config/default.yml file by app_name setting.

  2. Delete the folder config from the repository root

  3. Delete the Gemfile, Gemfile.lock and rakefile.rb files from the repository root

  4. Add the following scripts to your package.json file

    {
    "scripts": {
    "postinstall": "npx bower install --config.interactive=false",
    "build": "hub-scripts build"
    }
    }
  5. The Azure Pipeline requires that you have the test npm script defined.

    You may use exit 0 if you have no tests for your app but this is not recommended.

  6. Run the build in Azure DevOps to ensure it works.

  7. Archive the old project in TeamCity

    1. Find your application's TeamCity project
    2. Edit Project...
    3. Actions > Archive Project... > Archive
  8. (Optional) You may now move your repository from GitHub to Azure Git if desired.

Reverting#

We recommend archiving your TeamCity project to allow you to restore it in case something goes wrong during the migration process.

  1. Find your application's TeamCity project
  2. Edit Project...
  3. Actions > Dearchive Project... > Dearchive
  4. Redeploy to the environments that may need it using the previously deployed builds

Hub v1 and v2 with TeamCity#

Older Hub applications are built and released through TeamCity. Follow the instructions in Change Management for deployment.

New projects are created by copying the [Template] projects and setting the name and repository according to your app.

Reference#

Last updated on by Garrett Smith