Repository Configuration Guide

This guide explains how to configure your code repositories for GitStart development using our secure slicing technology.

Understanding Repository Slicing

GitStart developers work on “sliced” repositories—secure, isolated copies of portions of your codebase. This ensures:

• Your complete codebase remains private
• Only authorized portions are accessible to GitStart developers
• You maintain full control over what is shared

GitHub and GitLab Repository Setup

Setting Up GitHub Repositories

1. Install the GitStart GitHub App

   • A GitHub admin user must install the GitStart app
   • Navigate to the Integrations tab in the GitStart dashboard
   • Follow the prompts to authorize the app for your organization

2. Select Repositories

   • Choose which repositories you want GitStart to work with
   • You can add or remove repositories at any time

3. Configure Repository Slices

   • For each repository, specify:

     • Which folders to share and which to ignore

     • Environment variables needed for development

     • Build and run commands for local development

   Important: GitStart developers work in containerized environments based on your sliced repository. Proper configuration ensures they can replicate your development environment locally.

4. Verify Configuration

   • Build the sliced repository to confirm successful configuration
   • Review the build logs for any errors
   • Make adjustments as needed based on build results

Setting Up GitLab Repositories

GitLab integration requires a few additional steps:

1. Create a Bot Account
   • Create a new GitLab account with the prefix gitstart- (e.g., gitstart-bot)
2. Generate a Personal Access Token (PAT)
   • Follow GitLab’s guide to create a PAT
   • Grant the token sufficient permissions (api, read_repository, write_repository)
3. Configure Repository Access
   • Add the bot account to the GitLab Group containing your repositories
   • Assign appropriate permissions (typically Developer role)
4. Connect to GitStart
   • In the GitStart dashboard, navigate to the Integrations tab
   • Enter your GitLab domain (e.g., https://gitlab.com or https://gitlab.company.com)
   • Input the PAT you created earlier

Advanced Configuration

Manual Repository Slicing Configuration

For more precise control, you can create a git-slice.json file in your repository:

{
  "repoUrl": "https://github.com/{yourOrganization}/{yourRepo}.git",
  "folders": ["src/components", "src/utils", "tests"],
  "branch": "develop",
  "ignore": ["CODEOWNERS", "src/config/secrets.js"]
}

Key configuration fields:

Field	Description
repoUrl	The URL to your repository
folders	Specific folders/files you’re sharing with GitStart
branch	The branch we should work from
ignore	Files/folders to exclude from sharing

Environment Variables and Secrets

For local development, you may need to provide development environment variables:

• Development Variables: Configured in the GitStart dashboard and shared with developers
• Build Secrets: Used only during onboarding and slice configuration (not shared with developers)

Note: Never share production credentials. Use development or staging environment values where possible.

Repository Build Configuration

Supported Build Tools

GitStart supports standard build tools and package managers:

• npm, yarn, pnpm for JavaScript projects
• pip, poetry for Python projects
• Maven, Gradle for Java projects
• And many others

Custom Docker Configuration

For complex environments, you can upload a custom Dockerfile:

1. Navigate to the repository configuration in the GitStart dashboard
2. Select “Custom Docker Configuration”
3. Upload your Dockerfile or paste its contents

Troubleshooting

Common Build Issues

If your repository build fails, check for:

• Missing dependencies in shared folders
• Incorrect environment variables
• Build command errors

You can view detailed build logs in the GitStart dashboard to identify specific issues.

Need Help?

For assistance with repository configuration, contact our support team at support@gitstart.com or refer to our video instructions.