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

# GitHub

## Overview

With Knapsack, you can leverage GitHub's extensive ecosystem, including integration with GitHub Actions for CI/CD, advanced code review features, and seamless repository management. GitHub's user-friendly interface and powerful API make it a great choice for teams of all sizes.

### Cloud Authoring

To enable Cloud Authoring with GitHub, you need to install and configure our GitHub App.

#### [Install the GitHub App](https://github.com/apps/knapsack-cloud)

This app is essential for authenticating with your repository, allowing us to submit pull requests and merge code on your behalf.

### Important Steps

#### Step 1: Install the GitHub App

Ensure the GitHub App is installed for your Knapsack repository. This step is crucial for enabling seamless integration and functionality.

#### Step 2: Configure the App

Properly configure the app to authenticate and interact with your repository. This ensures smooth pull request submissions and code merging.

### Permissions Required

#### Please note that you must have the necessary GitHub Organization permissions to install and configure the app. Without these permissions, you will not be able to complete the setup.

By following these steps, you can fully leverage Cloud Authoring capabilities with GitHub, streamlining your development workflow.

For any questions or further assistance, please reach out to our team.

***

## GitHub Actions

### Required Repository Secrets

Deployments to Heroku rely on the following repository secrets:

1. `HEROKU_EMAIL` — The email associated with the Heroku account.
2. `HEROKU_API_KEY` — The API Key associated with the Heroku account (found in [profile settings](https://dashboard.heroku.com/account))
3. `HEROKU_GIT_URL` — Located on the app dashboard within Heroku's admin interface

Example main.yml

```yaml
name: Main

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Deploy
    if: github.ref == 'refs/heads/main'
    needs: [build]
    runs-on: ubuntu-latest
    env:
      HEROKU_EMAIL: ${{ secrets.HEROKU_EMAIL }}
      HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
      HEROKU_GIT_URL: ${{ secrets.HEROKU_GIT_URL }}
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
          ref: main
      - name: write auth
        run: |
          cat > ~/.netrc <<EOF
            machine git.heroku.com
              login $HEROKU_EMAIL
              password $HEROKU_API_KEY
          EOF
      - name: git push to heroku for deploy
        run: |
          git remote add heroku $HEROKU_GIT_URL
          git push heroku main

  build:
    name: Build & Release
    runs-on: ubuntu-latest
    steps:
      - name: Use actions/checkout@v2
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 18
      - name: Handle Cache
        uses: actions/cache@v2
        id: cache
        with:
          path: |
            node_modules
            **/node_modules
            ~/.cache/yarn
          key: node-deps-${{ hashFiles('yarn.lock') }}
      - name: Install Deps
        if: steps.cache.outputs.cache-hit != 'true'
        run: |
          yarn cache clean
          yarn install --cache-folder ~/.cache/yarn --prefer-offline --frozen-lockfile --force-node-version=16
        env:
          CYPRESS_INSTALL_BINARY: 0
      - name: Run Full Build
        run: yarn build
      - name: Run Knapsack Test
        run: yarn test
      - name: Release
        run: yarn auto shipit
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Deploy Job

The `deploy` job is responsible for deploying the application to Heroku. It only runs when changes are pushed to the `main` branch. This job depends on the successful completion of the `build` job. Here are the steps involved:

1. **Checkout Repository**: Uses the `actions/checkout@v2` action to fetch the entire repository history with a fetch depth of 0. This is required for deployment.
2. **Write Authentication**: Writes Heroku authentication details to the `.netrc` file to allow Git to authenticate with Heroku using the provided secrets (`HEROKU_EMAIL` and `HEROKU_API_KEY`).
3. **Push to Heroku**: Adds Heroku as a Git remote and pushes the `main` branch to Heroku for deployment.

### Build & Release Job

The `build` job handles the build and release process of the application. This job runs on every push to the `main` branch. Here are the steps involved:

1. **Checkout Repository**: Uses the `actions/checkout@v2` action to fetch the entire repository history with a fetch depth of 0. This ensures all branches and tags are available.
2. **Set Up Node.js**: Sets up Node.js version 18 using the `actions/setup-node@v1` action.
3. **Handle Cache**: Uses the `actions/cache@v2` action to cache `node_modules` and yarn cache directories to speed up subsequent builds. The cache key is based on the `yarn.lock` file hash.
4. **Install Dependencies**: Installs the project dependencies using Yarn if the cache is not hit. It skips downloading the Cypress binary to speed up the CI process.
5. **Run Full Build**: Builds the application by running `yarn build`.
6. **Run Tests**: Executes the test suite using `yarn test`.
7. **Release**: Releases the application using `yarn auto shipit`, which creates a release on GitHub. This step uses the `GH_TOKEN` secret for authentication with GitHub.