Troubleshooting Repository Setup

This guide provides solutions for common issues you might encounter when setting up repositories with GitStart.

Git Provider Connection Issues

GitHub Connection Troubleshooting

”I installed the GitHub App for another instance, do I need to do it again?”

Issue: You’ve previously installed the GitStart GitHub App and are creating a new agent/instance.

Solution: No, you don’t need to reinstall the app. Simply ensure that:

1. The GitStart GitHub App is installed for the new repositories you want us to work on
2. The app has the correct permissions for these repositories
3. Once configured, the repositories should appear in the “Select Repositories” step

”I cannot find my GitHub repository”

Issue: You’ve installed the GitStart GitHub App to your organization, but your repositories don’t appear in the selection list.

Solution:

1. Verify app installation:

   • Only organization owners can install GitHub Apps
   • Check the GitHub organization settings → GitHub Apps list to confirm installation

2. Check repository access:

   • In GitHub organization settings → GitHub Apps → GitStart App → Configure
   • Ensure either “All repositories” is selected or your specific repositories are in the “Only select repositories” list

   

GitLab Connection Troubleshooting

”I cannot find my GitLab repository”

Issue: You’ve connected the GitLab bot account but can’t find your repository in the selection list.

Solution: Our GitLab integration only works with repositories in GitLab Groups:

1. Check Group Membership:

   • Verify the repository is in a GitLab Group the bot account can access
   • Add the bot account as a member of that group

2. Move Repository to a Group:

   • Move your personal project to a group
   • Or convert a personal namespace into a group

This design follows the least privilege principle, giving GitStart access only to repositories you explicitly share.

Repository Slicing Issues

Understanding Slicing Concepts

”What is a slice?”

A slice is a subset of your repository that GitStart developers can access. This security feature ensures you control exactly which parts of your codebase are shared.

”Which branch should I specify in the slice configuration?”

The branch you specify is both:

• The source branch from which we create the slice
• The target branch to which we open pull requests

Typically, use your repository’s default branch. Alternatively, you can specify a separate branch, but ensure it exists in your repository.

Configuring Slices

”What’s the difference between ‘Share none of the files’ and ‘Share all the files’?”

These options control the default sharing behavior:

• “Share none of the files”: Nothing is shared by default

  • You must specify “Paths to slice” to include files
  • You can add exceptions to exclude specific files within included paths

• “Share all the files”: Everything is shared by default

  • You must specify “Paths to ignore” to exclude files
  • You can add exceptions to include specific files within excluded paths

You can verify what’s included in your slice using the “Preview the slice” panel.

Build and Environment Configuration

”What package managers are supported?”

GitStart currently supports:

• npm
• yarn

You can use any npm run or yarn run command. We automatically run npm install or yarn install before your build command, so you don’t need to include installation steps.

”What does ‘Use a Dockerfile’ do?”

This option allows you to build your repository using Docker instead of standard package manager commands:

1. Provide the “Dockerfile Path” (relative to repository root)
2. Specify the “Docker Build Context Directory”

Examples:

• Simple setup: Dockerfile at ./Dockerfile with context directory .
• Monorepo: Dockerfile at ./packages/backend/Dockerfile with context directory ./packages/backend/

”What environment variables are needed?”

Include any variables required to:

• Build and compile your code (even dummy values that don’t break the build)
• Run the application in a development or testing environment
• Enable GitStart developers to test functionality locally

Build Verification Failures

If your slice build fails during verification:

1. Review the error logs provided in the dashboard
2. Check for missing dependencies in your slice configuration
3. Verify environment variables are properly configured
4. Ensure build commands are correct

For persistent issues, contact our support team with the error logs for assistance.

Need Help?

If you encounter issues not covered in this guide, please contact our support team at support@gitstart.com.