Skip to content
GitStart's Documentation

Common Issues and Solutions

This guide addresses frequent challenges that may arise during your collaboration with GitStart and provides practical solutions.

Ticket Management Issues

Ticket Synchronization Problems

Issue: Tickets aren’t synchronizing properly between your ticketing system and GitStart.

Solutions:

  1. Check permissions: Ensure the GitStart integration has proper access to your ticketing system
  2. Verify filters: Confirm your ticket filters are correctly configured in the GitStart dashboard
  3. Check webhooks: For self-hosted systems, verify webhooks are properly configured and firing
  4. Wait for sync: Remember that synchronization may take up to 15 minutes in some cases

Media and Image Issues

Issue: Images from GitLab issues don’t load correctly in GitStart.

Solution: This is due to GitLab’s restrictions on Personal Access Tokens (PATs). Two options:

  1. Upload public images instead
  2. Change your GitLab project settings to make all images public by disabling “Enable authorization checks for all media files”

Cannot Edit Handed-Off Tickets

Issue: Unable to edit tickets created in GitStart after they’ve been handed off.

Solution:

  • For dashboard-created tickets: Currently, editing handed-off tickets isn’t supported
  • For synchronized tickets: Make changes in your original ticketing system, and they’ll sync to GitStart (may take a few hours)

Development Workflow Issues

Slow Response to PR Reviews

Issue: Development seems delayed after providing PR feedback.

Solutions:

  1. Check comment notifications: Ensure comments are being submitted properly in your repository
  2. Verify communication channels: Confirm your Slack/Teams integration is functioning
  3. Contact support: If developers haven’t responded within one business day, contact support@gitstart.com

Estimation Disagreements

Issue: GitStart’s estimates seem higher or lower than expected.

Solutions:

  1. Discuss with developers: Comment on the PR with your concerns
  2. Review ticket clarity: Check if requirements are clear and well-defined
  3. Contact your Technical Project Manager: They can help reconcile estimation differences
  4. Understand first-month calibration: Initial estimates may require adjustment as we learn your codebase

Scope Change Handling

Issue: Confusion about how to handle requirement changes during development.

Solutions:

  1. Minor changes: Comment directly on the PR
  2. Major changes: Create a new ticket to avoid disrupting workflow
  3. Urgent large changes: Contact your Technical Project Manager to discuss options

Technical Issues

Repository Access Problems

Issue: GitStart seems to have incorrect or insufficient access to your repository.

Solutions:

  1. Review slice configuration: Check if the correct files and folders are being shared
  2. Verify branch settings: Ensure the target branch exists and is properly configured
  3. Check app permissions: Verify the GitHub App or GitLab bot has the necessary permissions

Local Build Failures

Issue: GitStart developers report they cannot build or run your code locally.

Solutions:

  1. Review build logs: Check the error messages in the dashboard
  2. Update environment variables: Ensure all necessary variables are provided
  3. Verify dependencies: Confirm all required dependencies are included in the slice
  4. Consider Docker: For complex setups, provide a Dockerfile for consistent environments

PR Creation Failures

Issue: GitStart cannot create PRs in your repository.

Solutions:

  1. Check branch permissions: Verify GitStart has permission to create branches
  2. Review protection rules: Ensure branch protection rules don’t block GitStart
  3. Verify webhook connectivity: Confirm GitHub/GitLab webhooks are functioning

Communication Issues

Missing Notifications

Issue: Not receiving updates about ticket or PR status changes.

Solutions:

  1. Check notification settings: Review your preferences in the GitStart dashboard
  2. Verify communication channel: Ensure your Slack/Teams integration is correctly set up
  3. Check email filters: Make sure GitStart emails aren’t being filtered as spam

Developer Availability

Issue: Need to discuss a ticket but unsure how to reach the developer.

Solutions:

  1. Use PR comments: Leave comments directly on the pull request
  2. Message your shared channel: Use your Slack/Teams channel to ask questions
  3. Contact your Technical Project Manager: They can facilitate communication

Billing and Account Issues

Understanding Charges

Issue: Confusion about how costs are calculated for completed work.

Solutions:

  1. Review the Usage page: Check detailed cost breakdowns in your dashboard
  2. Examine PR details: Review the specific work completed for each charge
  3. Contact your Client Experience Manager: They can explain billing details

Managing Multiple Agents/Instances

Issue: Difficulty managing work across multiple repositories or projects.

Solutions:

  1. Use dashboard filters: Filter the dashboard view by agent/instance
  2. Set up dedicated channels: Create separate communication channels for each agent/instance
  3. Assign agent/instance owners: Designate specific team members to manage each agent/instance

Need Additional Help?

If you’re experiencing issues not covered in this guide:

  1. Contact your Technical Project Manager for development-related concerns
  2. Reach out to your Client Experience Manager for account or relationship questions
  3. Email support@gitstart.com for technical support
  4. Schedule a call with our team for complex issues requiring discussion