AI Security

Deploy Keys vs. GitHub Apps: Safely Connecting a Coding Agent to a Private Repository for Small Teams

Published 2026-09-24 by AISecAll Editorial

TL;DR: For small teams, use a read‑only Deploy Key for simple pull‑only tasks and a fine‑grained GitHub App for any write operations. Keep the key short‑lived, store it in a secret manager, rotate weekly, and log every push or pull made by the agent. Combine both methods when you need both read and write but want the strongest isolation possible.

What is the threat model for a coding agent that can push to a private repo?

An AI coding agent that can write code to a repository becomes a privileged insider. If the agent is compromised, an attacker could:

• Inject malicious code into production branches.
• Exfiltrate proprietary source files.
• Delete or rewrite commit history.

Because the agent runs automatically, traditional human review may be bypassed. The goal is to limit the agent’s reach to the smallest set of actions needed for the task.

Why Deploy Keys are a good fit for read‑only or limited‑write scenarios

Deploy Keys are SSH keys attached to a single repository. They cannot be used across multiple repos and do not grant access to the broader organization.

• Scope by design: a Deploy Key can be set to read‑only, preventing any push.
• Isolation: if the key is leaked, the attacker can only affect that one repo.
• Simplicity: no OAuth flow is required; the agent can authenticate with a static private key.

For agents that only need to fetch code (e.g., to analyze or refactor existing files), a read‑only Deploy Key is the least‑privilege choice.

How to create and rotate a Deploy Key securely

1. Generate a new SSH key pair on a hardened workstation:

   ssh-keygen -t ed25519 -C "ai‑agent‑deploy‑key" -f ai_deploy_key -N ""

2. Add the public key (ai_deploy_key.pub) to the target repository under Settings → Deploy keys → Add deploy key. Enable the Allow write access toggle only if the agent truly needs to push.
3. Store the private key (ai_deploy_key) in a secret manager (e.g., HashiCorp Vault, AWS Secrets Manager). Never hard‑code it in source.
4. Schedule a rotation job (weekly for read‑only, daily for write‑enabled keys). The job should:
   • Generate a fresh key pair.
   • Replace the old Deploy Key via the GitHub API (requires a personal access token with admin:repo scope).
   • Update the secret manager with the new private key.
5. Log the rotation event with timestamp, repo name, and key fingerprint. This log becomes part of your AI‑agent audit trail.

When a GitHub App is the better choice

GitHub Apps provide a richer permission model and can be scoped to multiple repositories, organization‑wide events, and specific API actions. Use an App when the agent must:

• Open pull requests across several repos.
• Trigger GitHub Actions or other webhooks.
• Access issue trackers, project boards, or secret scanning results.

Because Apps authenticate with JSON Web Tokens (JWT) that expire after ten minutes, they reduce the window of exposure compared to long‑lived SSH keys.

Setting up a fine‑grained GitHub App for a coding agent

1. In GitHub, create a new App (Settings → Developer settings → GitHub Apps → New GitHub App).
2. Give the App only the permissions it needs, for example:
   • contents: read & write on the target repo.
   • pull_requests: write if the agent creates PRs.
   • Disable any permissions you do not use (e.g., metadata, issues).
3. Generate a private key for the App and store it in a secret manager.
4. Implement the JWT flow in your agent code (see the OpenAI Agents docs for example OpenAI Agents documentation).
5. Record each JWT issuance and every API call the agent makes. Include the installation_id, endpoint, and request payload in the log.

Combining Deploy Keys and GitHub Apps for layered defense

Some workflows need both fast read access (e.g., cloning a large repo) and occasional writes (e.g., creating a PR). A hybrid approach can be:

• Use a read‑only Deploy Key for cloning. This avoids the overhead of the JWT flow for bulk fetches.
• When the agent is ready to push, switch to the GitHub App token, which is short‑lived and tightly scoped.

Because the two credentials are independent, compromise of one does not automatically grant the other.

Auditing and revocation checklist

Running this checklist weekly keeps the access surface small and gives you evidence for audits.

When you need a hands‑off, secure way to let an AI coding assistant touch your codebase, start with a read‑only Deploy Key, add a fine‑grained GitHub App for any write‑needs, and automate rotation and logging. If you need help designing the workflow or integrating secret‑manager rotation, AISecAll can run a short security‑review engagement for your team.