GitHub access for agents

GitHub access lets a Runlayer agent work on your code the way a developer does: git clone a repository into its sandbox, change files, run your tests, commit, push a branch, and open a pull request. The agent acts as a GitHub App that your organization owns, so every commit and push shows up as <your-app>[bot], never as a person.

GitHub access is enabled per workspace. If you don’t see GitHub App under Settings → Integrations, contact Runlayer to turn it on.

GitHub access vs the GitHub connector

These are two different things, and an agent can use both.

	GitHub connector	GitHub access
What the agent gets	MCP tools (search code, read issues, comment, review)	Real `git` in the agent’s sandbox (clone, commit, push)
Who it acts as	The person whose GitHub account is connected	Your organization’s GitHub App bot
Set up in	Connectors	Settings → Integrations and the agent’s GitHub access section
Good for	Reading and talking about GitHub	Changing code: fixes, refactors, dependency bumps, PRs

How it works

A GitHub org admin creates a GitHub App in your GitHub organization and installs it on the repositories agents may touch.
A Runlayer workspace admin connects that App in Settings → Integrations. Runlayer checks the credentials with GitHub before saving them.
A workspace admin grants the connection to an agent, optionally limited to specific repositories.
On every git network operation, the agent’s sandbox asks Runlayer for a token. Runlayer mints a short-lived (about one hour) installation token scoped to that agent’s repositories. No GitHub secret ships with the run or is written to disk.

What you need

On GitHub: an owner of the GitHub organization (or someone allowed to create and install GitHub Apps in it).
In Runlayer: a workspace admin with the Manage org settings capability (Super Admins have it). Both connecting the App and granting it to an agent need this capability, because a grant hands the agent the App’s reach.
An agent to grant access to. See Agents.

Set up

Create a GitHub App

In GitHub, open your organization’s Settings → Developer settings → GitHub Apps and click New GitHub App.

GitHub App name: anything you like, for example acme-runlayer-agents. Commits will show as acme-runlayer-agents[bot].
Homepage URL: any URL, for example your Runlayer workspace URL.
Webhook: clear Active. Runlayer does not use GitHub App webhooks.
Repository permissions:
- Contents: Read and write (required)
- Metadata: Read-only (GitHub sets this automatically)
- Pull requests: Read and write (optional; add it if agents should open pull requests)
Where can this GitHub App be installed? Only on this account.

Click Create GitHub App. Agents only ever get the permissions above, even if you give the App more.

Note the App ID and generate a private key

On the App’s settings page, copy the App ID shown under About.Scroll to Private keys and click Generate a private key. GitHub downloads a .pem file. Keep it safe: you paste it into Runlayer in a later step.

Install the App on your organization

On the App’s page, open Install App and click Install next to your organization. Choose All repositories or Only select repositories. Agents can never reach a repository the installation doesn’t include.After installing, copy the Installation ID: it is the number at the end of the installation page’s URL, for example https://github.com/organizations/acme/settings/installations/12345678.

Connect the App in Runlayer

In Runlayer, open Settings → Integrations, find GitHub App and click Connect GitHub App. Enter:

App ID
Installation ID
Private key: paste the whole contents of the .pem file, including the BEGIN and END lines

Click Connect. Runlayer checks the three values together with GitHub and reads the organization the App is installed on from GitHub itself. The private key is stored encrypted and never shown again.A workspace can connect one App per GitHub organization or account.

Grant the connection to an agent

Open the agent, go to the Agent tab and find GitHub access. Click Grant access, then:

GitHub App connection: pick the organization.
Repositories: add the repositories this agent may use, as owner/repo (for example acme/web). Every entry must belong to the connection’s organization. Leave the list empty to allow every repository the installation can access.

Click Grant access. Each agent can hold one grant at a time; to switch organizations or repositories, revoke it and grant again.The change applies to the agent’s next run.

Use it in a run

Ask the agent to work with HTTPS repository URLs. Git authenticates through Runlayer automatically; the agent never handles a password or personal access token.

Clone https://github.com/acme/web.git, fix the failing date formatting test in
src/utils/date.ts, run the test suite, commit on a new branch named
fix/date-format, push it, and open a pull request against main.

What to expect:

Clone, fetch, pull and push work for the granted repositories over https://github.com/.... SSH remotes (git@github.com:...) are not supported.
Commits are authored as the App’s bot (<app-name>[bot]), so GitHub links them to the App.
Pull requests need the App’s Pull requests: Read and write permission. The agent opens them through the GitHub REST API with the same credential, for example by reading it with git credential fill and calling POST /repos/{owner}/{repo}/pulls with curl. The gh CLI is not installed in the sandbox.
Branch protection and rulesets still apply. The agent can’t push to a protected branch or merge anything your rules don’t allow for the App.
Workflow files are off limits. Tokens never carry the workflows permission, so GitHub rejects pushes that change files under .github/workflows/.
Network access policy: if the agent uses an allow list, add github.com, and api.github.com if it opens pull requests.
Offline eval replays never get GitHub access.

Security model

Short-lived tokens. Each token lasts about an hour and is minted on demand. Nothing long-lived is stored in the sandbox.
Scoped twice. The installation decides which repositories the App can see on GitHub; the agent’s repository list narrows that further for each agent.
Minimal permissions. Tokens carry only Contents (read and write), Metadata (read) and, if the App has it, Pull requests (read and write). Other App permissions such as Workflows, Administration or Secrets never reach the agent.
Admins only. Connecting an App and granting it to an agent both need the Manage org settings capability. Agent owners without it don’t see the GitHub access section.
Audited. Connecting or deleting an App and granting or revoking an agent’s access appear in Audit Logs as github_app_installation_created, github_app_installation_deleted, installation_grant_created and installation_grant_revoked, with who did it and which repositories were granted.

Revoke access

One agent: in the agent’s GitHub access section, click the trash icon. The agent’s next git operation against GitHub fails, and the token it holds is revoked at GitHub.
Every agent using an App: in Settings → Integrations → GitHub App, delete the connection. All of its grants are revoked at once.
Disabled or deleted agents can’t get new tokens. For a disabled agent account, the token already in the sandbox is also revoked at GitHub within about a minute.
On GitHub: uninstalling the App or deleting its private key stops all access immediately.

To rotate the private key, generate a new key on GitHub, delete the connection in Runlayer, connect it again with the new key, and grant it to the agents again.

Troubleshooting

Symptom	What to do
No GitHub App section in Settings → Integrations	GitHub access isn’t enabled for your workspace yet, or you lack Manage org settings. Contact Runlayer or a workspace admin.
No GitHub access section on the agent	Only workspace admins see it. It is also hidden on the built-in Runlayer Assistant.
Grant access is disabled	Connect a GitHub App in Settings → Integrations first.
”GitHub rejected this App ID, installation ID and key together”	The three values don’t belong together. Check the App ID on the App’s page, the Installation ID from the installation URL, and that the key was generated for this App.
”The private key is not a readable PEM”	Paste the full `.pem` contents, including the `BEGIN` and `END` lines.
”A GitHub App is already connected for …”	That organization already has a connection. Delete it first to replace it.
”… is outside …, the account this GitHub App is installed on”	Repository entries must use the connection’s organization as the owner.
”This agent already has GitHub access; revoke it first.”	An agent holds one grant. Revoke the current one, then grant again.
Git asks for a username, or fails with “could not read Username”	The run has no GitHub access: the agent has no grant, or the remote isn’t an `https://github.com/...` URL. Grant access, then start a new run.
Git fails with “Runlayer git credentials: This agent has no GitHub access”	The grant was revoked during the run. Grant access again, then start a new run.
Git fails with “repository not found” or HTTP 403 on push	The repository isn’t in the agent’s list or the installation’s repositories, or the App lacks Contents: Read and write.
Opening a pull request fails with “Resource not accessible by integration”	Give the App Pull requests: Read and write on GitHub and accept the new permission on the installation. The next token picks it up.
`egress_denied` naming `github.com`	The agent’s network access policy blocks GitHub. Add `github.com` (and `api.github.com`) to its allow list.

Agents

Build, schedule and run agents

Agent Accounts

The identity every agent carries

GitHub connector setup

Give agents GitHub MCP tools that act as a user

Audit Logs

Review who granted which agent access to what

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

GitHub access for agents

GitHub access vs the GitHub connector

How it works

What you need

Set up

Use it in a run

Security model

Revoke access

Troubleshooting

Agents

Agent Accounts

GitHub connector setup

Audit Logs

​GitHub access vs the GitHub connector

​How it works

​What you need

​Set up

​Use it in a run

​Security model

​Revoke access

​Troubleshooting

​Related docs

Agents

Agent Accounts

GitHub connector setup

Audit Logs

GitHub access vs the GitHub connector

How it works

What you need

Set up

Use it in a run

Security model

Revoke access

Troubleshooting

Related docs