> ## Documentation Index > Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt > Use this file to discover all available pages before exploring further. # GitHub access for agents > Let an agent clone, commit, push and open pull requests on your repositories as your own GitHub App, with short-lived, repository-scoped tokens. 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 `[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](/platform-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 1. A GitHub org admin creates a GitHub App in your GitHub organization and installs it on the repositories agents may touch. 2. A Runlayer workspace admin connects that App in **Settings → Integrations**. Runlayer checks the credentials with GitHub before saving them. 3. A workspace admin grants the connection to an agent, optionally limited to specific repositories. 4. 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](/platform-agents). ## Set up 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. 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. 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`. 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. 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. ```text theme={null} 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 (`[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](/platform-agents#network-access-policy), 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](/platform-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. | ## Related docs Build, schedule and run agents The identity every agent carries Give agents GitHub MCP tools that act as a user Review who granted which agent access to what This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.