AI Security

Configuring Fine‑Grained GitHub Permissions for an OpenAI Coding Agent in Small Teams

Published 2026-09-05 by AISecAll Editorial

TL;DR: Use a personal access token (PAT) with only the repo:status, repo:invite, and contents:read/contents:write scopes needed for the specific repository. Store the token in a secret manager, rotate it every 30‑90 days, and enforce a short‑lived session in the OpenAI agent loop. Verify the agent’s actions with a human‑in‑the‑loop approval step before any push to main.

What minimal GitHub scopes does a coding agent actually need?

OpenAI’s Agents documentation shows that a coding agent can call the github tool via the tool_use API. The agent only needs the scopes required for the actions you allow it to perform:

• Read repository contents: repo:read (or the more granular contents:read for a single repo).
• Write new files or updates: repo:write (or contents:write).
• Create pull requests: pull_requests:write (included in repo scope).
• Check commit status: repo:status – useful if you run CI checks before merging.

Do not grant organization‑wide admin rights (admin:org) or delete_repo unless you have a very controlled workflow.

How to create a short‑lived, fine‑grained PAT for a single repository

1. Navigate to GitHub Settings > Developer settings > Personal access tokens.
2. Click Generate new token > Fine‑grained token.
3. Select the target repository only (e.g., my‑company/app‑backend).
4. Enable the following permissions:
   • Contents – Read and write
   • Pull requests – Read and write
   • Commit statuses – Read and write
5. Set an expiration date (30 days is a good baseline for a pilot).
6. Copy the token – you will never see it again.

Store the token in a secret manager (e.g., AWS Secrets Manager, GCP Secret Manager, or a simple encrypted file) and reference it from the agent’s environment variables, never hard‑coding it in code.

How to wire the token into the OpenAI agent loop

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

github_token = os.getenv("GITHUB_PAT")

# Define a tool that the agent can call
client.tools.register(
    name="github",
    description="Interact with a single GitHub repository",
    schema={
        "type": "object",
        "properties": {
            "action": {"type": "string", "enum": ["list", "read", "write", "pr"]},
            "path": {"type": "string"},
            "content": {"type": "string"},
            "branch": {"type": "string", "default": "main"}
        },
        "required": ["action", "path"]
    },
    handler=lambda params: run_github(params, github_token)
)

The run_github helper should enforce a whitelist of allowed paths (e.g., src/ only) and reject any attempt to delete files.

How to add a human‑in‑the‑loop approval before a push to main

Even with least‑privilege scopes, a mis‑prompted agent could produce unwanted code. Implement a two‑step flow:

1. The agent drafts a pull_request targeting a dev branch.
2. A Slack or email notification is sent to a designated reviewer with a link to the PR.
3. The reviewer either merges or rejects the PR. The agent only proceeds after receiving a “merge‑approved” webhook.

This pattern keeps the AI fast (the agent can continue other tasks) while ensuring a human gate before production changes.

What audit logs should you capture for GitHub interactions?

• Timestamp, agent ID, and request ID.
• Requested action (list, read, write, PR).
• Repository and branch targeted.
• Result (success, error, rejected by policy).
• Human approval decision ID (if applicable).

Send these logs to a centralized SIEM or a simple CSV in a secure bucket. The OWASP GenAI Security Project recommends logging all tool calls for traceability (OWASP GenAI).

How to rotate the token without breaking the agent

1. Generate a new fine‑grained PAT with the same scopes and a new expiration date.
2. Update the secret manager entry (most secret managers support versioning).
3. Restart the agent process or reload its environment – the next call will pick up the new token.
4. Revoke the old token after the new one is confirmed working.

Automate this rotation with a cron job that checks the token’s expiry date via the GitHub API.

When should you consider a self‑hosted Git server?

If your codebase contains regulated data (e.g., PHI, PCI) and you cannot rely on GitHub’s compliance attestations, move to a self‑hosted GitLab instance. The same fine‑grained token model applies, but you’ll need to host the secret manager yourself and adjust the API endpoint in the agent’s run_github helper.

Key takeaways

• Grant the agent the narrowest scopes needed for its task.
• Use fine‑grained PATs limited to a single repository.
• Store tokens securely and rotate them regularly.
• Require human approval before any merge to a protected branch.
• Log every tool call for auditability and incident response.

Following these steps lets a solo founder or a small team reap the productivity benefits of an OpenAI coding agent while keeping the codebase locked down.

If you need a quick review of your current GitHub token setup or help wiring the approval webhook, our team at AISecAll can run a short security audit and provide a hardened configuration guide.