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.
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 (firstname.lastname@example.org) 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).
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:
- Follow the guidelines in this article to get started.
- Navigate to "Service Hooks" under "Project Settings" (found in the bottom left corner).
- Click the "Add New" icon, then select "Web Hook". Proceed by clicking "Next."
- For the trigger, opt for "Pull request merge attempted".
- Ensure the appropriate repository is selected. Leave all other options set to "[Any]".
- Click "Next."
- In the settings section, input the following URL: https://api.knapsack.cloud/webhooks/azure.
- Conclude by clicking "Finish".
Steps to add the second web hook:
- Repeat steps above with trigger set to "Pull request updated"
- 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)
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
- group: Heroku
- stage: BuildAndTest
displayName: 'Install, Build, and Test'
- job: BuildAndTestJob
- task: NodeTool@0
displayName: 'Install Node.js'
- checkout: self
displayName: 'Checkout source code'
- 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
- script: |
git fetch --all --unshallow
git checkout main
- script: |
echo "machine git.heroku.com
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!
- We recommend making a very small change, to a README file perhaps, and then merging that directly into the
- Keep an eye on the Pipelines" area for a successful build and deploy.
- 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.
- Within the Knapsack UI — create a new branch and make a small visual change. This could be a simple text change or style adjustment.
- Merge your changes right in
- 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 email@example.com if you run into any issues along the way or would like to chat with a Solutions Engineer.