# How the Automation Scheduler Processes Cron Triggers in Background Agents

> Discover how the automation scheduler processes cron triggers in background agents. Learn how it checks Git commits for changes to intelligently enqueue image rebuild jobs.

- Repository: [Cole Murray/background-agents](https://github.com/ColeMurray/background-agents)
- Tags: internals
- Published: 2026-07-13

---

**The automation scheduler in the ColeMurray/background-agents repository processes cron triggers by executing a 30-minute interval check that compares remote Git commit SHAs using `git ls-remote`, enqueueing image rebuild jobs only when the source code has actually changed.**

The **ColeMurray/background-agents** repository implements a robust automation scheduler to keep sandbox environments current within the Modal serverless compute platform. Located in the Modal Infra package (`packages/modal-infra`), this scheduler leverages cron triggers to orchestrate periodic tasks without manual intervention. Understanding how the automation scheduler processes cron triggers reveals the efficiency mechanisms that prevent unnecessary computational overhead.

## Architecture of the Cron-Based Scheduler

The core automation scheduler resides in [`packages/modal-infra/src/scheduler/image_builder.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/src/scheduler/image_builder.py). According to the source code comments, the system performs "Scheduled rebuilds every 30 minutes (cron) with git ls-remote comparison" (line 9).

### The 30-Minute Cron Interval

The scheduler operates on a fixed **30-minute cadence**. This interval balances the need for fresh code against the cost of repeated image builds. The cron trigger fires automatically within the Modal worker environment, initiating the rebuild validation sequence.

### Git SHA Comparison Logic

When triggered, the scheduler executes the logic marked by the comment `# Scheduler: cron-based rebuild logic` (line 416). The process follows these steps:

1. **Fetch Remote State**: For each registered repository, the scheduler invokes `git ls-remote` to retrieve the latest commit SHA from the remote origin.
2. **Compare Stored Hash**: The fetched SHA is compared against the `last_built_sha` stored in the scheduler's persistent state.
3. **Conditional Enqueue**: Only when the SHAs differ does the scheduler call `enqueue_image_build()`, passing the repository ID and the new commit hash.

## Image Rebuild Workflow

Upon detecting a changed commit, the scheduler interacts with the control plane APIs defined in [`src/web_api.py`](https://github.com/ColeMurray/background-agents/blob/main/src/web_api.py). The workflow proceeds as follows:

- **Trigger Build**: The scheduler POSTs to `/build-image` with the new SHA.
- **Create Sandbox**: After a successful build, it may invoke `/create-sandbox` to provision fresh execution environments.
- **Update State**: The `last_built_sha` is updated in the database to reflect the newly built version.

This sequence ensures that background agents always execute against the most recent code without manual image management.

## Testing Cron Trigger Behavior

The [`packages/modal-infra/tests/test_scheduler.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/tests/test_scheduler.py) file contains integration tests that verify the cron logic. The test suite includes a "rebuild_images cron function" test that mocks control-plane responses.

The tests validate:
- **No-Op Scenarios**: When `git ls-remote` returns a matching SHA, no build task is queued.
- **Rebuild Triggers**: When SHAs differ, the test asserts that `enqueue_image_build` receives the correct parameters.

## Practical Implementation Examples

The following examples demonstrate the cron trigger implementation as found in the source code.

**Core cron handler from [`image_builder.py`](https://github.com/ColeMurray/background-agents/blob/main/image_builder.py):**

```python

# packages/modal-infra/src/scheduler/image_builder.py

async def run_cron():
    """
    Cron handler executed every 30 minutes.
    Rebuilds images only when remote commits differ from last built.
    """
    for repo in registered_repos:
        latest_sha = await git_ls_remote(repo.url)
        if latest_sha != repo.last_built_sha:
            await enqueue_image_build(repo.id, latest_sha)
            repo.last_built_sha = latest_sha

```

**Test verification from [`test_scheduler.py`](https://github.com/ColeMurray/background-agents/blob/main/test_scheduler.py):**

```python

# packages/modal-infra/tests/test_scheduler.py

def test_rebuild_images_cron():
    # Mock the control-plane endpoint returning latest commit SHA

    mock_post = mock_control_plane_latest_sha()
    
    # Execute cron handler

    result = await image_builder.run_cron()
    
    # Verify build queued only for changed repositories

    assert result == {"rebuilt": ["repo-A"], "skipped": ["repo-B"]}

```

## Summary

- The automation scheduler processes cron triggers via [`packages/modal-infra/src/scheduler/image_builder.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/src/scheduler/image_builder.py).
- It runs on a strict **30-minute interval** configured within the Modal worker environment.
- The trigger uses `git ls-remote` to fetch current commit SHAs and compares them against stored `last_built_sha` values.
- Image rebuilds only occur when the remote SHA differs, preventing redundant builds.
- Integration tests in [`packages/modal-infra/tests/test_scheduler.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/tests/test_scheduler.py) mock these interactions to verify correct cron behavior.

## Frequently Asked Questions

### How often does the automation scheduler check for code changes?

The scheduler executes its cron trigger **every 30 minutes**. This interval is hardcoded in the scheduler configuration to balance freshness with resource efficiency.

### What prevents unnecessary image rebuilds in the cron process?

The scheduler stores the `last_built_sha` for each repository. Before enqueueing a build, it compares the remote SHA from `git ls-remote` against this stored value. Only when the SHAs differ does it trigger a rebuild, eliminating redundant work for unchanged codebases.

### Which file contains the core cron logic for background agents?

The primary implementation resides in [`packages/modal-infra/src/scheduler/image_builder.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/src/scheduler/image_builder.py). This file contains the `run_cron()` function and the `# Scheduler: cron-based rebuild logic` comment marking the decision point for rebuilds.

### How is the cron trigger tested in the repository?

The test suite in [`packages/modal-infra/tests/test_scheduler.py`](https://github.com/ColeMurray/background-agents/blob/main/packages/modal-infra/tests/test_scheduler.py) mocks the control-plane interactions. It simulates `git ls-remote` responses to verify that the scheduler correctly identifies changed repositories and calls `enqueue_image_build()` only when appropriate.