GitHub App Setup

How Ovvoc connects to GitHub

Ovvoc uses the GitHub App model — not OAuth personal access tokens. This means fine-grained permissions, short-lived installation tokens, and per-repository access control. You can revoke access to any repository at any time without affecting others.

Permissions explained

The Ovvoc GitHub App requests only three permissions — the minimum needed to clone your code, push an update branch, and open a pull request:

permissions:
  contents: write          # Clone repo + push update branch
  pull_requests: write     # Create PRs with verified updates
  metadata: read           # Repository info (granted automatically)

# ovvoc NEVER requests:
#   - admin access
#   - organization settings
#   - repository settings
#   - secrets or environment access
#   - actions or workflow permissions

The contents:write permission allows Ovvoc to push to feature branches (e.g. ovvoc/update-lodash-4.17.21) but never directly to your default branch. All changes go through pull requests.

Installation flow

1. Sign in to your Ovvoc dashboard
2. Click "Add Repository"
3. GitHub redirects you to the App consent page
4. Select the repositories you want to monitor (or all repos)
5. Click "Install" to approve

After installation, GitHub sends a webhook to Ovvoc with your installation ID. Ovvoc stores this ID and begins monitoring the selected repositories immediately.

Token lifecycle

Ovvoc never stores long-lived credentials for your repositories. Instead, it requests a short-lived installation token for each job:

1. Job starts
   └─ ovvoc requests installation token from GitHub API
   └─ Token scoped to: specific repository, 1 hour expiry

2. Clone + Transform + Build + Test
   └─ Token lives only inside ephemeral container
   └─ Container has no network during build/test phases

3. PR creation
   └─ Token used to push branch + create PR

4. Job complete
   └─ Container destroyed
   └─ Token expires (or is already expired)
   └─ No credentials remain anywhere

Repository selection

You can add or remove repositories at any time from GitHub's settings:

• Adding a repo: Monitoring starts immediately. Ovvoc scans package.json and queues updates.
• Removing a repo: Active jobs are cancelled. All monitoring data for that repo is deleted.

To modify the repository list, go to GitHub → Settings → Applications → Ovvoc → Configure.

Troubleshooting

App not appearing in GitHub

• Verify you're in the correct GitHub organization
• You need admin access to the organization to install apps
• Try refreshing the GitHub page or signing out and back in

Permission errors

• If your organization requires admin approval for GitHub Apps, the org admin must approve the installation request
• Check the organization's third-party access policy in GitHub settings

Reinstalling

If you need to reinstall the Ovvoc App:

1. Go to GitHub → Settings → Applications
2. Find Ovvoc and click "Uninstall"
3. Return to your Ovvoc dashboard and click "Add Repository"
4. Install the App again with your desired repositories

Required permissions explained

The Ovvoc GitHub App requests the absolute minimum set of permissions needed to perform dependency updates. Here is exactly what each permission enables and why it is required:

• Contents: write — this permission lets Ovvoc create update branches (e.g. ovvoc/update-lodash-4.17.21) and push commits containing the updatedpackage.json, lockfile, and any transformed source files. It also allows Ovvoc to read your repository contents so it can clone the code into an ephemeral container for analysis and testing. Ovvoc never pushes directly to your default branch — all changes go through pull requests.
• Pull requests: write — this permission lets Ovvoc open pull requests on your repository after a successful pipeline run. The PR includes a confidence score, change summary, and full test output so your team can review before merging.
• Metadata: read — this permission is granted automatically to all GitHub Apps and provides basic repository information such as name, default branch, visibility, and language. It cannot be deselected.

We intentionally do not request any of the following permissions: admin access, organization settings, repository settings, secrets or environment variables, actions or workflow permissions, or deployment keys. Ovvoc operates on the principle of minimum access — it only asks for what it strictly needs to clone code, push a branch, and open a PR.

Organization vs personal accounts

The installation flow differs slightly depending on whether you are installing the Ovvoc App on a personal GitHub account or on an organization account.

Personal accounts

If you own the repository under your personal GitHub account, you can install the Ovvoc App directly. No approval from anyone else is required. Click “Add Repository” from the dashboard, select your repositories, and approve the permissions.

Organization accounts

Organization accounts may have policies that restrict third-party app installations. There are two common scenarios:

• You are an org admin: You can install the app directly, just like a personal account. The app will be available to all repositories you select within the organization.
• You are a member (not admin): When you attempt to install the app, GitHub will send an approval request to the organization admins. The installation will be pending until an admin approves it. You will see a “pending” status in your Ovvoc dashboard.

If your organization restricts third-party app access, ask your org admin to review the Ovvoc App’s permission manifest (shown above) and approve the installation request. The admin can find pending requests under Organization Settings → Third-party access.

Repository selection strategy

When installing the Ovvoc App, you can choose to grant access to all repositories in the account or select specific ones. Here are our recommendations for getting started:

• Start small: Select 1–3 repositories initially. This lets you observe Ovvoc’s behavior, understand the PR format, and build confidence before scaling.
• Pick repos with good test coverage: Ovvoc uses your test suite to verify that updates do not break anything. Repositories with comprehensive tests will produce higher confidence scores and more reliable results.
• Avoid auto-deploy repos initially: If your CI/CD pipeline automatically deploys when a PR is merged to the default branch, hold off on connecting that repo until you are comfortable with Ovvoc’s pull requests. Once you trust the process, you can safely add these repos and even set up auto-merge for high-confidence updates.
• Consider dependency count: Repositories with many outdated dependencies will generate more update jobs. This is useful for catching up on technical debt, but may produce a burst of PRs initially. Use the repository settings to set the update schedule to “weekly” if you prefer a slower rollout.

You can always add or remove repositories later from GitHub’s App settings page without reinstalling the app.

Additional troubleshooting

App not appearing in dashboard

If you installed the GitHub App but your repositories do not appear in the Ovvoc dashboard, try the following:

1. Sign out of Ovvoc and sign back in — this refreshes your GitHub access token
2. Reinstall the GitHub App from GitHub → Settings → Applications → Ovvoc → Configure
3. Verify the app is installed on the correct account (personal vs organization)
4. Check that you selected at least one repository during installation

Permission denied errors

If Ovvoc reports permission errors when trying to clone or push to a repository:

• Verify the app has contents:write permission on that specific repository
• Check that the repository has not been archived or made read-only
• Ensure branch protection rules do not block the Ovvoc bot from pushing to feature branches

Installation stuck

If the installation appears to be stuck in a pending state:

• For organization accounts, check if admin approval is required (see above)
• Try removing the app entirely from GitHub settings and re-adding it from the Ovvoc dashboard
• Clear your browser cache and try the installation flow again

Webhook not firing

If Ovvoc is not detecting new pushes or repository changes:

• Go to GitHub → Settings → Applications → Ovvoc → Advanced
• Check the Recent Deliveries section to see if webhooks are being sent
• Look for failed deliveries (non-2xx response codes) and check the error details
• If no deliveries appear, the webhook URL may be misconfigured — reinstall the app

Security review

Understanding exactly what Ovvoc can and cannot access is important for your security posture. Here is a clear breakdown:

What Ovvoc accesses

• Source code (read): Ovvoc clones your repository into an ephemeral container to scan dependencies, analyze imports, and apply code transforms. The container is destroyed after the job completes.
• Source code (write): Ovvoc pushes update branches containing modified package.json, lockfile, and any transformed source files. It never pushes to your default branch.
• PR metadata: Ovvoc creates pull requests with descriptions, confidence scores, and test results. It reads PR status to track merge outcomes.

What Ovvoc never accesses

• Secrets and environment variables — Ovvoc has no permission to read repository or organization secrets
• Deployment keys — Ovvoc does not interact with deploy keys or SSH credentials
• CI/CD configuration — Ovvoc cannot read, modify, or trigger GitHub Actions workflows
• Organization settings — Ovvoc has no access to billing, members, teams, or org-level configuration
• Repository settings — Ovvoc cannot change branch protection rules, webhooks, or collaborator access

All source code processed by Ovvoc exists only inside ephemeral containers for the duration of the pipeline run. No source code is stored persistently on Ovvoc’s servers. For organizations that require code to never leave their infrastructure, see the Self-Hosted Agent documentation.