GitLab | Knapsack Documentation

Overview

Integrating Knapsack with GitLab allows you to take full advantage of its built-in CI/CD capabilities, streamline your workflows, and ensure that your design system components are always up-to-date and well-managed. GitLab’s self-hosted and cloud options provide flexibility to meet your organization’s needs.

Cloud Authoring

Authentication through Personal Access Token (PAT)

To enable cloud authoring within GitLab, we use a Personal Access Token (PAT) for authentication. This token allows secure access to your GitLab repositories and enables necessary actions on your behalf.

Step 1: Add Knapsack Bot as a Collaborator

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

Permissions Required

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.

Step 2: Knapsack Generates PAT for Authentication

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

For any questions or further assistance, please contact our support team.

Important Notes

This is a manual process. If handling asynchronously, we’ll notify you when it is completed.

Mandatory Step

This step must be completed for Cloud Authoring to function.

GitLab CI

Required CI/CD Variables

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

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

Configuration notes:

For an easy GitLab integration with Heroku — we are utilizing the Ruby gem dpl
When adding CI/CD variables — mark them as Protected so only pipelines on protected branches can read them, and mark HEROKU_API_KEY as Masked. The example below deploys only from main, which GitLab protects by default; if main isn’t protected in your project, protect it first, because protected variables aren’t passed to pipelines on unprotected branches.

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