Azure: Cloud Authoring and Deployments


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 ( 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.


#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:
  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


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.


  • 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



- main


vmImage: ubuntu-latest


- group: Heroku


- stage: BuildAndTest

displayName: 'Install, Build, and Test'


- job: BuildAndTestJob


- task: NodeTool@0


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'


- job: DeployToHerokuJob


- checkout: self

fetchDepth: 0

persistCredentials: true

- script: |

git fetch --all --unshallow

git checkout main

git pull

- script: |

echo "machine


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 if you run into any issues along the way or would like to chat with a Solutions Engineer.