GitLab: Cloud Authoring and Deployments

Introduction

This document will cover the steps necessary to complete your migration to your own GitLab 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

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

To set up authentication through a PAT, we ask that you add our Knapsack Bot (knapsack-bot@knapsack.cloud) to your repository as a collaborator with the necessary permissions.

You can do this by following these steps:

  1. Navigate to your repository on GitLab and click on the "Settings" tab.
  2. In the left-hand sidebar, select "Members".
  3. Under "Invite members to the project", enter "knapsack-bot@knapsack.cloud" in the "Username or email" field.
  4. Set the access level to "Maintainer" or "Owner" to ensure that the bot has the necessary permissions to perform actions on your repository.
  5. Click "Invite" to send the invitation to the Knapsack Bot.

Note: that you may need administrative privileges on your repository to invite the Knapsack Bot as a collaborator. If you encounter any issues, please reach out to our support team for assistance.

IMPORTANT

Once the Knapsack Bot has been added as a collaborator, we will use its account to generate a PAT for authentication. This allows us to access your repository securely without requiring your personal credentials.

  • We recommend that you DO NOT share your PAT with anyone else to ensure the security of your repository.
  • This is a manual process. If handling asynchronously, we'll notify you when this process is completed.
  • This step must be completed in order for Cloud Authoring to function.

Deployments

In addition to cloud authoring, we also support seamless deployment options for your GitLab repositories using Heroku and GitLab CI/CD.

The following sections will break down all aspects of reconnecting deployments to Heroku. First we will breakdown the required CI/CD variables that enable deployments to Heroku.

Heroku: Required CI/CD variables

Deployments to Heroku rely on the following CI/CD variables being set:

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

GitLab CI/CD

In this example we will use GitLab’s CI/CD Pipelines system as the continuous delivery mechanism to push our deployments to Heroku.

Configuration notes:

  • For an easy GitLab integration with Heroku — we are utilizing the Ruby gem dpl
  • When adding CI/CD variables — do not mark them as protected or CI will not catch them

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 DPL and the Heroku CLI, then fires off the deployment

.gitlab-ci.yml 

stages:
  - build
  - deploy

Build_Main:
  image: node:16
  stage: build
  script:
    - yarn
    - yarn build
  cache:
    key: knapsack-build
    paths:
      - node_modules
  only:
    - main

Deploy_Main:
  image: ruby:2.6
  stage: deploy
  before_script:
    - echo 'Deploying to heroku...'
    - gem install dpl -v ">= 1.10.15"
    - wget -qO- https://cli-assets.heroku.com/install-ubuntu.sh | sh
  script:
    - dpl --provider=heroku --app=$HEROKU_APP --api-key=$HEROKU_API_KEY
  only:
    - main

Putting it all together 🎉

Now that you've configured the required CI/CD variables and the GitLab CI/CD — 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 "CI/CD > 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