Prerequisites

A GitHub account
At least one npm repository with a package.json
A test suite is recommended (Ovvoc uses it to verify updates)

Step 1: Create your Ovvoc account

Head to the sign in page and authenticate with your GitHub account. Ovvoc uses GitHub OAuth so there's no separate password to manage.

Step 2: Install the GitHub App

After signing in, click "Add Repository" from your dashboard. You'll be redirected to GitHub to install the Ovvoc App. Select the repositories you want Ovvoc to monitor and approve the permissions:

Permissions

Repository permissions:
  Contents:        read & write   # Clone repo, push update branch
  Pull requests:   write          # Create PRs with verified updates
  Metadata:        read           # Repository info (automatic)

Ovvoc never requests admin, organization, or settings permissions. You can revoke access per-repository at any time.

Step 3: Select a repository

Back on the dashboard, you'll see your connected repositories. Ovvoc immediately scans each repository's package.json and lockfile:

Scan output

Scanning express-api-server...
  Found 42 dependencies (28 prod, 14 dev)
  4 outdated packages detected
  1 security advisory (moderate)

  Queued: [email protected] (security patch, priority: high)
  Queued: [email protected] (breaking change, priority: normal)
  Queued: @types/[email protected] (type stub, priority: low)
  Queued: [email protected] (devDep, priority: low)

Step 4: Your first update

Ovvoc processes updates automatically. Each runs through the full 10-stage pipeline inside an isolated container:

Pipeline

[1/10] Detect    ✓  lodash 4.17.20 → 4.17.21 (security patch)
[2/10] Clone     ✓  Cloned into ephemeral container
[3/10] Analyze   ✓  1 dependency to update
[4/10] Classify  ✓  Category 4: Security patch (no code change)
[5/10] Plan      ✓  Strategy: version-only
[6/10] Transform ✓  No code changes needed
[7/10] Install   ✓  npm install [email protected]
[8/10] Build     ✓  npm run build — passed (2.1s)
[9/10] Test      ✓  npm test — 47/47 passed (8.3s)
[10/10] PR       ✓  Created PR #42 with confidence: 1.0

Step 5: Review and merge

When all tests pass, Ovvoc opens a pull request on your repository with a confidence score and a detailed description of what changed.

package.json (before)

  "dependencies": {
-   "lodash": "^4.17.20"
  }

package.json (after)

  "dependencies": {
+   "lodash": "^4.17.21"
  }

Review the diff, check the test results in the PR description, and merge when ready. If tests had failed, you'd get a detailed failure report instead — your main branch is never affected.

What's next

Update Pipeline — understand the 10-stage process
Dashboard Guide — navigate repos, jobs, and PRs
Update Categories — all 25 categories explained

System requirements

Before connecting your first repository, make sure your project meets these requirements:

Runtime and tooling

Node.js 18 or later — Ovvoc containers run Node.js 24 internally, but your project must target Node.js 18+ to ensure compatibility with modern dependency versions
npm 8 or later — required for lockfile v3 support and the npm audit signatures Ovvoc relies on
git — your repository must be hosted on GitHub

Supported package managers

npm (default) — full support including package-lock.json v2 and v3
yarn v1 (Classic) & v2+ (Berry) — supported via yarn.lock detection
pnpm — supported via pnpm-lock.yaml detection. Workspace protocols are handled automatically
bun — supported via bun.lockb detection

Repository structure

Your repository must have a package.json in the root directory. For monorepos, Ovvoc automatically detects workspace roots defined via the workspaces field in the root package.json, or via pnpm-workspace.yaml. Each workspace package is scanned and updated independently, but coordinated updates (like React + React DOM) are grouped into a single pull request when a group rule applies.

If your project uses a non-standard structure — for example, the application code lives in a subdirectory like packages/app without a workspace configuration — you can specify the root path in your repository settings on the dashboard.

Post-setup verification

After installing the GitHub App and connecting your first repository, run through this checklist to confirm everything is working correctly:

Dashboard shows your repositories. Navigate to the Repositories page. You should see each repo you selected during installation with a status of Monitoring or Scanning (the initial scan runs automatically).
Dependency count matches package.json. Click into a repository and verify the total dependency count lines up with the number of entries in your dependencies and devDependencies fields. If the count is off, check that your package.json is valid JSON and committed to the default branch.
At least one update detected or “all up to date” shown. The Updates page lists every detected version change. If your dependencies are already current, you will see an “all up to date” message instead — that is a valid result.
Test your build and test scripts locally. Before expecting Ovvoc to produce clean results, verify that npm run build and npm test pass on your machine. Ovvoc runs these exact commands inside its containers. If they fail locally, they will fail in the pipeline too.
Check the billing page. Visit the Billing page to confirm your plan is active and the repository count matches what you expect. The first billing cycle starts when you connect your first repository.

If any step does not look right, check the GitHub App Setup guide for troubleshooting tips, or reach out to support.

Recommended next steps

We recommend a gradual rollout strategy so you can build confidence in Ovvoc’s updates before applying them to mission-critical repositories.

Start with low-risk repositories

Pick one or two internal tools, side projects, or staging applications — repositories where a bad merge would not affect production users. This lets you observe Ovvoc’s behavior (branch naming, PR format, test execution) in a safe environment.

Enable auto-update for patch and minor versions first

Categories 1–6 (version bumps, lockfile regeneration, type stubs, security patches, devDependencies, and peer alignment) require no code changes and have a 99%+ success rate. Turning on automatic updates for these categories lets you immediately benefit from dependency freshness without any risk of code breakage.

Review your first 3–5 PRs manually

Even for low-risk updates, take the time to read the PR description, check the diff, and verify the test output. This builds familiarity with how Ovvoc structures its pull requests and what the confidence score means in practice. After a handful of successful merges, you will have a clear baseline for what to expect.

Expand to production repositories

Once you are comfortable with the workflow, add your production repositories and enable the full range of update categories (7–25). For breaking-change updates (categories 14+), Ovvoc will include a confidence score below 1.0 — review these PRs more carefully and pay attention to the AI-assisted sections highlighted in the PR description.

Fine-tune per-repo settings

Use the repository settings page to customize update schedules, exclude specific packages that you manage manually, and set the target branch for PRs. See the Dashboard Guide for a full walkthrough of available settings.

Quickstart