Repository caching is a powerful feature that dramatically speeds up your Overcut automation workflows by storing and reusing repository content and dependencies. Instead of cloning repositories and installing dependencies from scratch every time, Overcut intelligently caches this information to reduce wait times and improve efficiency.

​
What is Repository Caching?

Repository caching works by storing a snapshot of your repository (including code, dependencies, and build artifacts) after the first run. On subsequent runs, Overcut can use this cached version to skip the time-consuming steps of cloning and installing dependencies.

First Run

Repository is cloned, dependencies are installed, and everything is cached for future use.

Subsequent Runs

Cache is used to skip cloning and dependency installation, dramatically reducing startup time.
Dependency Caching is Key: While caching repository code provides some speed benefits, caching installed dependencies can save significantly more time. Installing dependencies (npm install, pip install, etc.) often takes much longer than cloning the repository itself. Enabling “Pre install and cache dependencies” in your repository settings can reduce workflow execution time by 70-90% in many cases.

​
Benefits

  • Faster Workflow Execution: Skip repository cloning and dependency installation
  • Reduced Resource Usage: Less network bandwidth and storage operations
  • Improved Reliability: Consistent environment across multiple runs
  • Better User Experience: Faster response times for your automation workflows

​
How It Works

​
Automatic Cache Management

Overcut automatically manages your repository caches:
  1. Cache Creation: On the first run, Overcut creates a cache containing your repository and dependencies
  2. Cache Usage: Subsequent runs use the cached version for faster execution
  3. Cache Refresh: Caches are automatically refreshed in the background to keep them up-to-date
  4. Cache Invalidation: Old caches are automatically cleaned up to save disk space

​
Cache Scope

Each cache is isolated by:
  • Workspace: Different workspaces never share cache content
  • Repository: Each repository has its own cache
  • Provider: GitHub, GitLab, Bitbucket, etc. are cached separately
This ensures that your workspace data remains private and secure.

​
How Overcut Updates Cached Repositories

When using a cached repository, Overcut doesn’t just restore the old version - it intelligently updates it to get the latest changes:
1

Restore from Cache

Overcut extracts the cached repository to your working directory, including all files, Git history, and dependencies.
2

Checkout Target Branch

The system switches to your target branch (or the default branch if none specified) and ensures it’s up-to-date.
3

Pull Latest Changes

Finally, Overcut pulls the latest changes to ensure your working directory contains the most recent code.
This process ensures that while you benefit from the speed of cached dependencies and repository structure, you always get the latest code changes for your workflow execution.
Smart Branch Handling: Overcut automatically detects whether the target branch exists in the cached version and either checks it out or creates it from the remote, ensuring seamless branch switching. Even if the cache was created from a different branch, Overcut will fetch and checkout the requested branch automatically.

​
Configuration

​
Enabling Cache for a Repository

You can control caching on a per-repository basis:
1

Access Repository Settings

Go to your repository in the Overcut dashboard and click on the repository name to access settings.
2

Enable Cache

In the repository configuration, toggle “Enable Cache” to turn on caching for this repository.
3

Configure Dependencies (Optional)

Optionally enable “Pre install and cache dependencies” to cache installed packages and reduce installation time.

​
Cache Settings

Cache Enabled

Master toggle to enable or disable caching for the repository.

Include Dependencies

When enabled, dependencies are pre-installed and cached, further reducing setup time.
Maximize Your Time Savings: The “Include Dependencies” option is where you’ll see the biggest performance gains. A typical Node.js project might take 2-3 minutes to clone but 5-15 minutes to install dependencies. With dependency caching enabled, subsequent runs can skip the entire installation process, making your workflows dramatically faster.

​
Required: Dependency Installation Commands

To enable dependency caching, you must provide the command that installs dependencies for your project. This is configured in the Tools section of your repository settings:
1

Access Tools Section

In your repository configuration, scroll down to the “Tools” section below the cache settings.
2

Configure Install Dependencies Tool

Look for the “Install dependencies” tool and provide the appropriate command for your project:
  • Node.js: npm install or yarn install
  • Python: pip install -r requirements.txt or poetry install
  • Ruby: bundle install
  • Go: go mod download
  • Custom: Any command that installs your project dependencies
3

Enable Dependency Caching

Once the install command is configured, you can enable “Pre install and cache dependencies” in the cache settings.
Built-in Tools: Overcut provides several built-in tools including “Install dependencies” with a placeholder command. You must customize this command to match your project’s dependency management system for caching to work properly.

​
Advanced Features

​
Smart Cache Eligibility

Overcut intelligently determines when cache can be used based on your workflow configuration:
  • Standard Clones: Cache is used for normal repository cloning
  • Sparse Checkouts: Cache is bypassed when using sparse checkout (as it changes repository structure)
  • Partial Clones: Cache is used with partial clone filters (blob limits, tree depth)
  • Force Fresh Clone: Use the ignoreCache option on the git.clone step to bypass cache when needed

​
Automatic Cache Refresh

Caches are automatically refreshed in the background:
  • Refresh Trigger: Caches older than 10 days trigger a background refresh
  • Invalidation: Caches older than 20 days are considered stale and won’t be used
  • Non-blocking: Cache refresh never blocks your workflow execution

​
Best Practices

​
When to Use Cache

  • Frequently accessed repositories: Repositories used in multiple workflows
  • Stable dependencies: Projects with consistent dependency requirements
  • Regular automation: Workflows that run multiple times per day

​
When to Bypass Cache

  • Debugging: Use ignoreCache when investigating cache-related issues
  • Dependency changes: When you need to test with fresh dependencies
  • Sparse checkouts: When using sparse checkout features

​
Dependency Management

  • Use lockfiles: Ensure your project has package-lock.json, yarn.lock, or similar
  • Consistent versions: Keep dependency versions consistent across environments
  • Regular updates: Periodically refresh caches to get latest dependency updates

​
Troubleshooting

​
Common Issues

Cache Not Working

Check that caching is enabled in repository settings and the repository is active.

Stale Dependencies

Dependencies may be outdated. Trigger a manual cache refresh or wait for automatic refresh.

Cache Size Issues

Large repositories may take longer to cache. This is normal for the first run.

Permission Errors

Ensure your repository has proper access permissions configured.

​
Updating Dependencies

To update dependencies in your cached repository, you can instruct the agent to run the dependency installation command before starting their main task:
1

Add Dependency Update Step

In your workflow, add a step that runs your dependency installation command before the main agent task.
2

Use the Install Dependencies Tool

Reference the “Install dependencies” tool you configured in your repository settings. For example:
  • Node.js: npm install (updates to latest compatible versions)
  • Python: pip install -r requirements.txt --upgrade
  • Ruby: bundle update
3

Agent Continues with Updated Dependencies

The agent will then proceed with the updated dependencies for their main task.
Smart Dependency Updates: When you instruct the agent to run dependency installation, Overcut will use the updated dependencies for that run. However, the cache itself is only updated during explicit cache refresh cycles, not after normal agent runs. This means the next run will start with the cached dependencies, but the agent can update them as needed for the current task.

​
Integration with Workflows

Repository caching works seamlessly with the git.clone step.

​
Getting Started

To start using repository caching:
  1. Enable for a Repository: Go to repository settings and toggle caching on
  2. Run Your Workflow: The first run will create the cache
  3. Enjoy Faster Runs: Subsequent executions will use the cached version
  4. Monitor Performance: Check execution logs to see cache usage
Repository caching is disabled by default for repositories.