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#
CreationThe 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.
Create the following
azure-pipelines.yml
file in the root of your repository to extend the build pipeline template provided byazure-devops
.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.
Set the
homepage
property in yourpackage.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.
Go to
iQmetrix / Your Project / Pipelines
and selectNew Pipeline
.- Connect: Select
GitHub
- Select: Select your repository
- Configure: Your
azure-pipelines.yml
file should be detected automatically. If not, selectExisting Azure Pipelines YAML file
andazure-pipelines.yml
- Review: Press
Save and run
- Connect: Select
#
UsageWe recommend following SemVer for versioning your applications. The
version
property frompackage.json
is automatically included in the/ping
file at build time.
Go to
iQmetrix / Your Project / Pipelines
and select your app.Deploy to Integration
If you set up the trigger in your pipeline, this will occur automatically with a commit to
master
- Select:
Run pipeline
- Choose your branch
- Select:
Run
- Your app build will run and, once complete, will deploy to Integration.
- Select:
Promote to further environments
Make sure you follow all Change Management protocols when releasing beyond Int. See Change Management section down below.
- Select the build you would like to promote
- Under the environment you would like to deploy to, select
0/1 checks passed
Approve
the checkIf you are unable to approve the check, ensure you have the permission to do so.
- The deploy will run, and once complete, your app will be live.
#
Change ManagementAll 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 StepInform 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.
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 torun
button and select the right build.
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.
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
toenvironment
- 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:
link to release site (TeamCity or Azure DevOps)
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 NotesTo 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- 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.
- Change Management will forward CM tickets for production Hub app changes to KM as a redundancy check.
#
Template#
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 ProjectFollow 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 ConnectionsThe 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
#
Open your Azure DevOps project
In the sidebar, at the bottom, click on the
Project settings
Now, go to the menu
Service connections
Create a new service connection for
SharedMicroservices-Development
andSharedMicroservices-Production
If you do not have permissions to create these service connections, request them from cloudops@iqmetrix.com
- Create a
New service connection
of typeAzure Resource Manager
- Select
Service principal (automatic)
- Set
Subscription
according to the subscription you are connecting to - Set
Service connection name
toSharedMicroservices-Development
orSharedMicroservices-Production
Save
- Create a
BuildAndDeploySharedResources resource group
#
Refer to the Create and manage a Service Connection - Shared connections to Azure subscriptions and other resources`
#
EnvironmentsIn order to defer your releases to later environments until manual approval is granted, you must add approvals.
- Open your Azure DevOps project
- In the sidebar, under Pipelines, select
Environments
- Create all required environments with no resources
Int
RC
Demo
Prod
- For each environment that you want to require a manual approval prior to releasing:
- Select the environment in the list
- Select
Approvals and checks
- Select
Approvals
- Add your team as an approver for the environment
#
Azure Key Vault Access PolicyIf 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.
- Navigate to the hub-build Azure Key Vault Access Policies
Add Access Policy
- Under
Select principal
, select the principal associated with your previous created service connection toSharedMicroservices-Development
- Under
Secret permissions
selectGet
andList
Add
Save
#
Hub v1 and Azure DevOpsYou 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
andHub.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.
Follow the same steps as described in the Pipeline - Creation.
Don't forget to add your
homepage
setting as defined in yourconfig/default.yml
file byapp_name
setting.Delete the folder
config
from the repository rootDelete the
Gemfile
,Gemfile.lock
andrakefile.rb
files from the repository rootAdd the following scripts to your
package.json
fileThe 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.Run the build in Azure DevOps to ensure it works.
Archive the old project in TeamCity
- Find your application's TeamCity project
Edit Project...
Actions
>Archive Project...
>Archive
(Optional) You may now move your repository from GitHub to Azure Git if desired.
#
RevertingWe recommend archiving your TeamCity project to allow you to restore it in case something goes wrong during the migration process.
- Find your application's TeamCity project
Edit Project...
Actions
>Dearchive Project...
>Dearchive
- Redeploy to the environments that may need it using the previously deployed builds
#
Hub v1 and v2 with TeamCityOlder 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.