GitHub

Two locks on every call#

Straza decides whether one of the agent's roles covers the repo a call names, and a repo no role covers stops there: ghapp never sees the call. ghapp then makes sure the call can touch only that repo. It checks who is calling, that the name is exactly GitHub's spelling and that the repo id is the one Straza approved, and makes a token for that one repo with only the tool's permissions.

The App's private key and every token stay in ghapp. GitHub sees each action as the App's bot account, and a footer names the agent on pull requests, issues and comments. ghapp works only behind Straza: without it, use GitHub's own MCP server or gh.

git push through Straza#

The agent types plain git push. Straza's holder, a service on the same machine under its own OS account, reads the branch and the commits, asks Straza for a grant naming exactly those, and sends the push to ghapp with the grant and a proof signed by its own key. ghapp checks both, compares the push with the grant, and streams it to GitHub with a token that stays in ghapp, so the code never passes through Straza's MCP traffic.

A grant is spent once, and a push may create and update branches under refs/heads/ only: no deletes and no tags. git_fetch and git_push are the tools a role binds for git; called over MCP, they check the repo and give the plain git command, and hand out nothing that opens git. The App gets no Workflows permission, so GitHub refuses a push that changes .github/workflows.

Roles and tools#

Three suggested application roles, split by risk; each reaches only this server. Risk comes from the MCP annotations the server declares on each tool and what each tool does, read in its code.

Register with strazad#

Installing also creates the server’s administration role, mcp-admin-ghapp, which your IGA can assign to the people who maintain it.

1. Install the manifest below.
   shellCopy

   strazactl apps install -f ghapp.yaml

2. Store the server’s credential. strazactl asks for it at a hidden prompt.
   shellCopy

   strazactl apps secret set ghapp

3. Store the listing credential. Straza sends it to repo_list alone, lists the repos with it, and lists them again every 10 minutes.
   shellCopy

   strazactl apps secret set ghapp --listing
   strazactl apps objects ghapp

4. Create the suggested roles, each on every repo. A role on this server says which repos it covers, so the roles go in as a role file. Save this as ghapp-roles.yaml:
   yamlCopy

   apiVersion: straza.dev/v1beta1
   kind: Role
   metadata:
     name: ghapp-read
   spec:
     kind: application
     server: ghapp
     bindings:
       - app: ghapp
         tools: [repo_list, repo_get, branch_list, file_get, pr_list, pr_get, issue_list, issue_get, search_code, search_issues, git_fetch]
         covers: every
   ---
   apiVersion: straza.dev/v1beta1
   kind: Role
   metadata:
     name: ghapp-write
   spec:
     kind: application
     server: ghapp
     bindings:
       - app: ghapp
         tools: [pr_create, pr_comment, issue_create, issue_comment, git_push]
         covers: every
   ---
   apiVersion: straza.dev/v1beta1
   kind: Role
   metadata:
     name: ghapp-admin
   spec:
     kind: application
     server: ghapp
     bindings:
       - app: ghapp
         tools: [pr_merge]
         covers: every

   Then open a draft from it and run the strazactl drafts publish command that the draft prints.
   shellCopy

   strazactl drafts create -f ghapp-roles.yaml

5. To keep a role to some repos, name them under covers. repo_list reaches every repo, so such a role leaves it out.
   yamlCopy

   apiVersion: straza.dev/v1beta1
   kind: Role
   metadata:
     name: ghapp-write-payments
   spec:
     kind: application
     server: ghapp
     bindings:
       - app: ghapp
         tools: [pr_create, pr_comment, issue_create, issue_comment, git_push]
         covers:
           objects: [ghapp-straza-test/pay-api, ghapp-straza-test/pay-web]

The manifest#

From Straza's guide Limit a role to some objects, with the objects block that ghapp's tool marks declare, the git tools included; its URL is that guide's demo stack value.

apiVersion: straza.dev/v1beta1
kind: App
metadata:
  name: ghapp
  namespace: ai.straza
  description: GitHub through one GitHub App, a token per call for one repo
server:
  name: ai.straza/ghapp
  description: Repos, pull requests and issues on GitHub. Each call gets a GitHub token for the one repo it names.
  repository:
    url: https://github.com/strazahq/ghapp-mcp-server
    source: github
  version: "0.1.0"
straza:
  runtime:
    kind: remote
    remote:
      url: http://ghapp:3003/mcp
  credential:
    kind: static
    inject:
      as: header
      name: Authorization
      template: "Bearer {{secret}}"
  exposure:
    tools: ["*"]
  limits:
    rps: 10
  objects:
    type: repo
    list:
      tool: repo_list
    tools:
      branch_list: { argument: repo }
      file_get: { argument: repo }
      git_fetch: { argument: repo }
      git_push: { argument: repo }
      issue_comment: { argument: repo }
      issue_create: { argument: repo }
      issue_get: { argument: repo }
      issue_list: { argument: repo }
      pr_comment: { argument: repo }
      pr_create: { argument: repo }
      pr_get: { argument: repo }
      pr_list: { argument: repo }
      pr_merge: { argument: repo }
      repo_get: { argument: repo }
      repo_list: all
      search_code: { argument: repo }
      search_issues: { argument: repo }

Credentials#

What the server reads at start to reach GitHub, through a GitHub App you install:

• GHAPP_APP_ID: the GitHub App's id (required). The repo's docs/github-app.md lists the permissions each tool needs
• GHAPP_PRIVATE_KEY or GHAPP_PRIVATE_KEY_FILE: the App's private key, as PEM or as a path; it never leaves the server (required)
• GHAPP_MCP_GATEWAY_SECRET: a bearer only the gateway holds, the secret that strazactl apps secret set stores; ghapp's own log then cannot name the agent, though Straza's audit can
• GHAPP_MCP_OIDC_ISSUER, GHAPP_MCP_OIDC_AUDIENCE, GHAPP_MCP_OIDC_CLIENTS: optional: accept tokens from this identity provider, with this audience, from these clients only, each of which signs in with Straza's client assertion key alone
• GHAPP_MCP_LISTING_TOKEN: opens repo_list and nothing else, the listing credential that strazactl apps secret set --listing stores
• GHAPP_API_URL: optional: GitHub's API, https://api.github.com by default

Server-side gates#

Settings the server reads at start. Each one switches writes on or registers more tools, as listed; a tool the server does not register does not exist for any role.

• GHAPP_PUBLIC_URL: the address Straza's holder reaches ghapp's git endpoint at. With --http and GHAPP_GIT_GRANT_ISSUER, Straza's public URL, it turns on git transport and registers git_fetch and git_push.
• GHAPP_MCP_READ_ONLY: true leaves out pr_create, pr_comment, pr_merge, issue_create, issue_comment and git_push, and refuses every push.

Related posts#

• BlogRole-based access control for AI agents