# How we keep dependencies up to date

The upgrade agent we run on Kortix — a weekly cron that opens dependency PRs, runs the full suite in a sandbox, and only opens the PR when it's green.

Canonical page: https://openchatly.com/use-cases/dependency-upgrades

Dependencies drift. Left alone, a project falls months behind, security patches
pile up, and the eventual upgrade turns into a large, risky change nobody wants
to own. The usual bots open a PR for every bump and leave a human to work out
whether each one is safe, which mostly means the PRs sit unreviewed.

We run an upgrade agent on Kortix that does the checking before it asks for a
review. A weekly cron proposes upgrades, applies them in an isolated sandbox,
runs the full suite, and only opens a PR when the change is green. This write-up
covers how the setup works: the trigger, the session model, and the guardrails.

- **Team:** Kortix
- **Runs on:** A weekly cron
- **Connected systems:** GitHub · CI
- **Mode:** Cron-driven · PR opened only when green

## The problem

Keeping dependencies current is work no one schedules. A version-bump bot opens a
PR per package, but it can't tell whether the bump breaks anything — that check
still falls to a person, so the PRs queue up and the project drifts anyway.

The common fixes are incomplete. Ignoring upgrades until something forces the
issue turns a routine bump into a migration. Merging bot PRs on green CI trusts
whatever tests already exist, not that the upgrade is actually safe. Doing it by
hand is reliable but slow, and it's the first thing dropped when the team is busy.

## What we built

On Kortix, a weekly cron triggers an upgrade agent. Each run spawns an isolated
session (a cloud sandbox) with scoped access to the repository and CI. The agent
checks which dependencies are behind, applies the upgrades on a branch, installs
clean, and runs the full suite inside the sandbox. It opens a PR only when the
change is green; a human merges.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the upgrade skill and the weekly trigger, and
opens a change request for you to review. Prefer clicks? Choose **Use this
template** instead.

**Setup prompt**

```
Set up a weekly dependency upgrade agent in this workspace.

1. Create the agent agents/dep-upgrader.md. Its job is to keep the dependencies of owner/repo current. It may use a GH_TOKEN secret for GitHub and open pull requests.

2. Create the skill skills/dependency-upgrade/SKILL.md with these rules:
   - Read memory/dependency-upgrade-log.md first. Skip pinned packages and resume any open upgrade pull request.
   - Group patch and minor upgrades into one batch. Apply each major upgrade on its own, with its migration in the same commit.
   - Run the full suite in the sandbox: install, typecheck, lint, build, unit tests, integration tests and audit.
   - Open a pull request only when every check passes. A partial pass counts as a fail.
   - When a major upgrade fails and the fix is more than about 30 lines, revert it and file an issue.
   - Never hand-edit the lockfile, never downgrade, and never merge the pull request.

3. Add a cron trigger weekly-upgrades to kortix.yaml. It runs the dep-upgrader agent every Tuesday at 05:00 with the prompt "Load the dependency-upgrade skill and run one complete upgrade sweep on owner/repo."

4. Tell me which of these connectors are not connected yet.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Add a GitHub token as the `GH_TOKEN` secret in your workspace. The agent uses it
to push its branch and open the pull request. Secrets are encrypted and injected
at runtime, scoped to the agents you grant them to.

- **GitHub** (Required):
Upgrades dependencies on a branch and opens a PR when green.
- **CircleCI** (Optional):
Runs the pipeline on the upgrade branch.
- **Linear** (Optional):
Tracks each deferred or failed upgrade as an issue.

### Run it once with this prompt

Merge the change request, then start a session with the **dep-upgrader** agent
and send this prompt. Read the pull request and its verification
results before you let the schedule take over.

**Prompt**

```
Run one dependency upgrade sweep on owner/repo.

1. Read the upgrade ledger and check for open upgrade pull requests.
2. List outdated dependencies and split them into patch, minor and major.
3. On a new branch, apply the patch and minor upgrades together, then each major upgrade one at a time.
4. Run install, typecheck, lint, build, tests and audit after each step.
5. If everything passes, open one pull request with each bump and its changelog. Do not merge it.
6. Log what you dropped or deferred, and why.
```

### Let the weekly schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every Tuesday at 05:00, each run in a new session on its own cloud
computer. The ledger in memory carries pins and deferred upgrades from one week
to the next.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: weekly-upgrades
    name: Weekly dependency upgrades
    on:
      cron: "0 0 5 * * 2"
    run:
      agent: dep-upgrader
      prompt: Load the dependency-upgrade skill and run one complete upgrade sweep on owner/repo.
```

### Open a pull request only when every check passes

A failing upgrade never becomes a pull request. The agent reverts it, logs
it and files an issue. When the full suite passes, it opens one pull request and
stops. A person reviews it and merges it.

### Review the pull request

Each run ends with one green pull request or a logged reason why there is none.
This is what a run looks like in the session:

> **Weekly dependency upgrades · Tue 05:00**
>
> Prompt: Load the dependency-upgrade skill and run one complete upgrade sweep on owner/repo.
>
> Upgraded **17** packages: **14** patch and minor bumps and **3** majors. The
> full suite passed, and the pull request is open for review. **1** more major
> upgrade failed the typecheck, so it was reverted and filed as an issue.

> **The pattern**
> A weekly **trigger** spawns a session with scoped **connectors** into the repo
> and CI. The upgrade playbook is encoded as **skills** and **memory**. The agent
> proves the change green in its sandbox and a human owns the merge.

## Make it do more

Once it works, paste any of these into the same session.

**Fix vulnerabilities first**

```
When the audit finds a vulnerability with a fix available, upgrade that package first and give it its own pull request.
```

**Explain each major upgrade**

```
For each major upgrade, add the breaking changes from its changelog and the files you changed to the pull request body.
```

**Monthly pin review**

```
On the first Tuesday of each month, list every pinned package with its pin reason and how far behind latest it is.
```

## Guardrails

The agent changes dependencies and runs code, so the access is scoped and
contained:

- **Isolation.** Every run happens in its own isolated sandbox on its own branch.
  The session can install, resolve, and run the suite to prove an upgrade; only
  the branch and result are written back out.
- **Scoped secrets.** The GitHub and CI credentials are encrypted in the secrets
  manager and injected into the sandbox at runtime, scoped to the agents you grant them to or
  the logs.
- **PR-gated.** The agent opens a pull request and stops. It never merges and
  never pushes to the default branch; a human owns the merge.
- **Everything is code.** The agent's configuration, skills, and permissions are
  files in the repo, versioned and changed through a reviewed **change request**
  rather than a dashboard setting.

## The outcome

- **Weekly:** Upgrades proposed on a schedule, not when something breaks
- **Green-only:** PRs opened only after the full suite passes
- **Human merge:** The agent proves the change; the team decides

Dependencies stay current without anyone scheduling the work, and the upgrade PRs
that land in review have already been run against the full suite. Reviewers see a
green change with the changelog attached instead of a bump they have to check out
and test by hand.
