Azure: Cloud Authoring and Deployments

Introduction

This document will cover the steps necessary to complete your migration to your own Azure Organization with Heroku deployments.

This is step 4 out of 4 in the process of migrating your Knapsack workspace. If you need to start at the beginning, please visit this article.

Cloud Authoring

Authentication through PAT

This step must be completed in order for Cloud Authoring to function

To enable cloud authoring and deployments to Heroku within Azure, we handle authentication through the use of a Personal Access Token (PAT). This token allows us to securely access your Azure repositories and perform necessary actions on your behalf.

Please note this is a manual process. If handling asynchronously, we'll notify you when the process is completed.

Two options to set up authentication through a PAT:

#1: Add our Knapsack Bot (knapsack-bot@knapsack.cloud) to your repository as a collaborator with the necessary permissions. We will handle generating the token.

Note: you may need administrative privileges on your repository to invite the Knapsack Bot as a collaborator.

OR

#2: Generate a token and delivery it securely (we can do this over a live session).

Web Hooks

Integrating Repository Events with the Knapsack API

To synchronize repository-related events with the Knapsack UI, it's crucial to set up webhooks. Specifically, we'll configure two web hook triggers. This ensures that when pull requests (PRs) are closed in Azure, corresponding changes are reflected in the Knapsack UI, like removing a branch from the active branch list.


Steps to add the first web hook:

  1. Follow the guidelines in this article to get started.
  2. Navigate to "Service Hooks" under "Project Settings" (found in the bottom left corner).
  3. Click the "Add New" icon, then select "Web Hook". Proceed by clicking "Next."
  4. For the trigger, opt for "Pull request merge attempted".
  5. Ensure the appropriate repository is selected. Leave all other options set to "[Any]".
  6. Click "Next."
  7. In the settings section, input the following URL: https://api.knapsack.cloud/webhooks/azure.
  8. Conclude by clicking "Finish".

Steps to add the second web hook:

  1. Repeat steps above with trigger set to "Pull request updated"
  2. All other settings should match the previous above steps

Deployments

In addition to cloud authoring, we also support seamless deployment options for your Azure repositories using Heroku and Azure Pipelines.

The following sections will break down all aspects of reconnecting deployments to Heroku. First we will breakdown the required repository secrets that enable deployments to Heroku.

Heroku: Required Repository Secrets

Deployments to Heroku rely on the following repository secrets being set:

  • HEROKU_APP — The name of the Heroku application
  • HEROKU_EMAIL — The email address associated with the Heroku account
  • HEROKU_API_KEY — The API Key associated with the Heroku account (found in profile settings)

Azure Pipelines

In this example we will use Azure's Pipelines system as the continuous delivery mechanism to push our deployments to Heroku.

Example:

  • In the below example we have setup very simple build and deploy jobs.
    • Build — handles installing dependencies and a simple build
    • Deploy — handles installing the Heroku deployment

azure-pipelines.yml 

trigger:
  - main

pool:
  vmImage: ubuntu-latest

variables:
  - group: Heroku

stages:
  - stage: BuildAndTest
    displayName: 'Install, Build, and Test'
    jobs:
      - job: BuildAndTestJob
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '16.x'
            displayName: 'Install Node.js'
          - checkout: self
            fetchDepth: 0
            displayName: 'Checkout source code'
            persistCredentials: true
          - script: yarn install
            displayName: 'yarn install'
          - script: yarn build
            displayName: 'yarn build'
          - script: yarn test
            displayName: 'Knapsack Test'

  - stage: Deploy
    displayName: 'Deploy to Heroku'
    jobs:
      - job: DeployToHerokuJob
        steps:
          - checkout: self
            fetchDepth: 0
            persistCredentials: true
          - script: |
              git fetch --all --unshallow
              git checkout main
              git pull
          - script: |
              echo "machine git.heroku.com
                login $(HEROKU_EMAIL)
                password $(HEROKU_API_KEY)" > ~/.netrc
            displayName: 'Write authentication credentials'
          - script: |
              git remote add heroku $(HEROKU_GIT_URL)
              git push heroku main
            displayName: 'Git push to Heroku for deploy'

Putting it all together 🎉

Now that you've configured the required repository secrets and the Azure Pipelines — it's time to test things out!

  1. We recommend making a very small change, to a README file perhaps, and then merging that directly into the main  branch.
  2. Keep an eye on the Pipelines" area for a successful build and deploy.
  3. Visit your newly deployed Knapsack workspace and verify everything deployed successfully.

Testing Cloud Authoring

Now that everything is hooked up, building, and deploying — it's time to test Cloud Authoring.

  1. Within the Knapsack UI — create a new branch and make a small visual change. This could be a simple text change or style adjustment.
  2. Merge your changes right in
  3. Wait about 5-10 minutes for the full deploy to complete —> Verify your changes made it live 🎉

Reach out to your Knapsack representative or email us at help@knapsack.cloud if you run into any issues along the way or would like to chat with a Solutions Engineer.

Related Articles