> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.knapsack.cloud/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.knapsack.cloud/_mcp/server.

# GitLab

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

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](mailto:knapsack-bot@knapsack.cloud)" in the "Username or email" field.
4. Set the access level to "Maintainer" or "Owner" to ensure the bot has the necessary permissions to perform actions on your repository.
5. 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:

1. `HEROKU_APP` — The name of the Heroku application
2. `HEROKU_API_KEY` — The API Key associated with the Heroku account (found in [profile settings](https://dashboard.heroku.com/account))

#### **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 .gitlab-ci.yml

```yaml
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
```

### In this example

#### Build\_Main

Handles installing dependencies and a simple build.

#### Deploy\_Main

Handles installing DPL and the Heroku CLI, then fires off the deployment.