> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Repositories

> How Overcut uses repositories, scopes automation, and enables per-repo customization for optimal agent performance.

## Repositories as the Foundation of Overcut Automation

In Overcut, repositories are the primary units for automation. All workflows, triggers, and agent actions are scoped to the repositories you connect and activate in your workspace.

Connected repositories also make repository-backed skills available for discovery in your project. When a repository is connected, Overcut can surface reusable skills that teams can review and add in the project-level **Skills** area.

## Repository Scope: Which Events Are Processed?

* **Only events from active repositories are processed.**
* When you connect a repository to Overcut (via **Settings → Integrations → Git**), you define the scope for all automations.
* Overcut listens for events (pull requests, issues, pushes, etc.) **only** from these active repositories.
* This ensures that automations run only where you intend, and that agents have access to the right code and context.

<Info>
  Inactive or unconnected repositories are ignored by Overcut. To automate a new repo, connect and activate it in your workspace settings.
</Info>

## Register a new Git Organization

To start automating with a new git, you must first register the organization.

<Steps>
  <Step title="Navigate to Git Integration">
    From the main menu click on **Git Integration**.
  </Step>

  <Step title="Connect Git Provider">
    Click on **Connect Git Provider**.
  </Step>

  <Step title="Select the Git provider">
    Select the Git provider you want to connect. (GitHub, GitLab, etc.) and click on **Connect**.
  </Step>

  <Step title="Grant Overcut the necessary permissions">
    You'll be redirected to GitHub to grant Overcut the necessary permissions for a specific organization or account.
  </Step>

  <Step title="Configure settings for Overcut's GitHub App">
    After selecting your preferred account or organization, you'll be led to the configuration page. You can configure the GitHub App to only allow access specific repositories in your account, or allow Overcut to access all of your repositories.
  </Step>
</Steps>

## Adding a New Repository to Overcut

To start automating with a new repository, follow these steps:

<Steps>
  <Step title="Navigate to Git Integration">
    From the main menu click on **Git Integration**.
  </Step>

  <Step title="Select the Git provider">
    Click on the organization you want to add a repo from.
  </Step>

  <Step title="Open the repositories modal">
    Click **Add Repository**.
  </Step>

  <Step title="Select the repository you want to add">
    From the modal, select the repository you want to add. Only repositories with access permissions will be shown.
  </Step>

  <Step title="Confirm and save your changes">
    Confirm and save your changes.
  </Step>
</Steps>

<Info>
  Only repositories that are connected and active will be included in Overcut automations and skill discovery.
</Info>

## Discover skills from connected repositories

Connected repositories can surface reusable skills for your team. This helps you turn repository guidance into shared project skills instead of repeating the same instructions across individual agents.

When you open the project-level **Skills** area and choose to add a skill, Overcut lets you scan connected repositories for reusable skills your workspace can access. From there, your team can:

* Browse available skills from connected repositories
* Preview a skill's `SKILL.md` instructions before adding it to the project
* Confirm where a skill comes from so you can choose the right one for the project

This keeps repository access and skill discovery aligned. If a repository is not connected to your workspace, its skills are not available to add.

<Tip>
  Use connected repositories to centralize reusable guidance for your team. After you add a skill at the project level, you can assign it to the agents that need it.
</Tip>

## Configuring a Repository for Optimal Agent Performance

Once your repository is connected, you can configure it to ensure agents work optimally with its unique tech stack and requirements. Workspace admins can tailor the agent environment, instructions, and commands for each repository.

<Frame>
  <img src="https://mintcdn.com/overcut/OA5WSuUPfS8g_FS6/images/repositories/repositories.png?fit=max&auto=format&n=OA5WSuUPfS8g_FS6&q=85&s=f5a4bf8d307325645637e4cfcdb8fe5f" width="3072" height="1728" data-path="images/repositories/repositories.png" />
</Frame>

<Steps>
  <Step title="Navigate to Repository Settings">
    Go to the repository settings in Overcut (usually found under the Integrations or Repositories section).
  </Step>

  <Step title="Select the Repository">
    Choose the repository you want to configure.
  </Step>

  <Step title="Choose the Agent Image">
    Select the container environment agents use for this repository. The **Default Image** suits most stacks, while **Universal 6** provides a newer toolchain for repositories that need more recent language or runtime versions. See [Agent Image](/docs/repositories/agent-image) for the full comparison.
  </Step>

  <Step title="Add Special Instructions">
    Provide any custom workflow steps, environment setup, or compliance requirements in Markdown or YAML. Examples: pre-commit hooks, build steps, environment setup, or compliance checks. These instructions will be used by agents during automation runs.
  </Step>

  <Step title="Define Custom Tools & Commands">
    Specify repo-specific commands for tasks like install, lint, test, or build. Agents will use these commands to interact with your codebase, ensuring compatibility with your repo's processes.
  </Step>

  <Step title="Link Ticket Repositories to Code Repositories">
    If your workspace uses ticket repositories, you can link them to related code repositories from the ticket repository page. See [Repository Mapping](/docs/repositories/repository-mapping) for details.
  </Step>

  <Step title="Save Your Configuration">
    Save your changes to apply the configuration.
  </Step>
</Steps>

## Code Indexing

Code indexing provides agents with an additional semantic search tool to find relevant code context efficiently. When enabled, agents can search for code by meaning rather than just keywords, helping them identify APIs, understand code relationships, and locate relevant files faster.

<Note>
  **Semantic search is optional for agent operation.** Agents can work effectively without code indexing by using standard tools like file search, grep, and glob patterns to navigate the codebase. Code indexing is an enhancement that provides another way to find context, but it is not required.
</Note>

## Summary

* Overcut only processes events from active, connected repositories.
* Each repo can be configured for optimal agent performance: custom images, instructions, and tools.
* This flexibility ensures automations are reliable, secure, and tailored to each codebase.

## Next Steps

Once you have your repositories configured, you may want to learn about **Repository Mapping & Automatic Identification** to understand how to:

* Link ticket repositories to code repositories
* Use AI-powered repository identification in your workflows
* Automatically select the most relevant repositories for each ticket

<Info>
  Learn more about repository mapping and automatic identification in our <a href="/docs/repositories/repository-mapping">Repository Mapping guide</a>.
</Info>