start using GitHub with your agents
sign up, open a project, and authorise GitHub from its connectors settings.
a pull request, an issue or a failed ci run is usually the moment someone wants an agent to start. connecting github to a project turns those moments into runs: an agent subscribes from a chat, and the next matching event starts a run with the event already in hand, in that chat or in a new chat in the same project when the routine opens one per event. the same connection lets agents move code between a repository and the conversation's sandbox. anything beyond that, opening a pull request, reviewing one, commenting on an issue, goes through github's own mcp server.
subscribing from a chat
github_subscribe takes a resource, the events to watch, and what the agent should do when one arrives. a pull request routine covers every pull request in owner/repo, or one as owner/repo#123. an issue routine works the same way. workflow and job routines fire when a run succeeds or fails, for the whole repository or for one workflow file or job name. the intent comes back with every notification, github_unsubscribe takes an event routine off again, and the project's Settings → Routines lists every routine the agents hold.
each notification carries the event routine, the actor, a one-line summary and a link. where github sends text, it carries that too: the description of a new pull request or issue, the body of a comment, and the body of a review that approves or requests changes. the text is fenced off as untrusted data and capped at 4,000 characters, so a stranger's comment can inform the agent but cannot instruct it.
moving code with git sync and push
github_git_sync clones a repository the installation can reach into the conversation's sandbox, or fetches if it is already there. agents edit files and run the build and the test suite over bash on that machine, then github_git_push pushes the current branch or any refspec back, so a new branch needs no separate step. both run authenticated git on the server side, and the credential never enters the agent's shell.
that is where the connector stops. it pushes a branch, but pull requests, reviews and comments need github's mcp server.
going beyond triggers with github's mcp server
for pull requests, reviews, comments and issues, add github's mcp server to the same project. it acts as the owner of the token you give it, under your organisation's token policies.
- create a github personal access token that can reach the repositories the project works on.
- open the project's Settings → Connectors, and under MCP servers press Marketplace.
- install GitHub. the add form opens with the url filled in and Send an authentication header switched on.
- leave Header name as
Authorization, enterBearerfollowed by your token as the Token, for exampleBearer github_pat_..., and save.
github's mcp server offers no browser sign-in aldena can use, which is why it takes a token. once it is connected, agents reach its tools through mcp_search and mcp_call, each tool gets its own row in the project's permissions, and every action runs as the person whose token it is, not as aldena. the mcp servers page covers the rest.
example tasks
- 01
take issue 88, write the fix, and push it to a new branch.
the agent syncs the repo to the conversation's sandbox, edits the files, runs the test suite over bash, commits, and pushes a new branch. with github's mcp server connected, it opens the pull request too.
github_git_syncbashgithub_git_pushmcp_call - 02
whenever someone comments on pr 412, answer it if it is a question.
each comment starts a run in this chat with the comment's text in the notification. the agent replies on the pull request through github's mcp server, or here in the chat when the project has none.
github_subscribemcp_call - 03
when ci fails on main, find out why.
a workflow routine starts a run on each failure. the agent syncs the repository, reproduces the failing step over bash, and reports the cause and a proposed fix in this chat.
github_subscribegithub_git_syncbash
what it will not do
the connector does not read pull requests, issues or files through the github api, and it does not open, review, merge or comment on anything. repository settings, secrets and org administration are out of reach. an agent cannot reach a repository the installation was never given, and no event starts a run while the connection waits for a reconnect.
what starts a run
every GitHub event an agent can subscribe to, grouped by resource. an agent subscribes from a chat with github_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event.
pr.createdpr.updatedpr.approvedpr.unapprovedpr.mergedpr.declinedpr.commentedreview.changes_requested
issue.createdissue.updatedissue.commented
workflow.succeededworkflow.failed
job.succeededjob.failed
what you grant
the GitHub app is installed once, and every token aldena mints from it is narrowed to exactly this access, whatever else the installation holds. there is nothing to pick.
- Metadata (read)
metadata:readSee which repositories the installation covers.
- Contents (write)
contents:writeClone and fetch repositories into the project's sandbox, push the branches agents create there, and read skill and agent files for the one-time import.
- Pull requests (read)
pull_requests:readCheck that a pull request an agent subscribes to exists.
- Issues (read)
issues:readCheck that an issue an agent subscribes to exists.
how to connect GitHub
connecting GitHub takes one authorisation round trip, started from inside the project that needs it.
- open the project's connectors settings
connections belong to a project, not to your account or the team. open the project that needs GitHub, go to settings → connectors, and press connect. other projects stay untouched.
- authorise with a real account
any member of the project can start the connection, and they authorise as themselves. GitHub asks only for the fixed access listed above, with no scopes to choose.
- an agent subscribes from a chat
ask an agent in a project chat to watch something in GitHub. it calls github_subscribe with the resource, events and intent, and settings → routines lists each routine it holds.
- a matching event starts a run
each matching event starts a run with the event and its content in hand, in the chat where the agent subscribed or in a new chat in the same project when the routine opens one per event. disconnecting GitHub stops every subscription to it.
data handling and security
a connector holds one credential and turns GitHub events into runs. the credential stays inside the project that connected it, and event text is data, never instructions.
- one connection, one project
the GitHub credential is stored against the project it was authorised in. no agent in another project can use it, and there is no team-wide connection to inherit by accident.
- tokens encrypted at rest
the GitHub token is encrypted before it is stored, and it never appears in a chat or in an agent's prompt. agents get the events, not the credential.
- events only where a routine watches
aldena verifies each delivery came from GitHub. an event starts a run only for a routine it matches, in the chat that set the routine up or in a new chat in the same project when the routine opens one per event. nothing starts while the connection needs a reconnect.
- event content is untrusted
event text may come from a stranger. it reaches the agent as fenced data capped at 4,000 characters, and the agent is told never to follow instructions in it.
- revocation is one click
disconnect GitHub and the project's event routines on it stop at once, along with the stored credential.

each GitHub tool agents hold has its own allow, ask or deny row in the project's permissions. see human in the loop for approvals and isolated projects for isolation.
faq
what does the github connector let an agent do?
it starts runs from pull request, issue, workflow and job events, and moves code between a repository and the conversation's sandbox. anything else needs github's mcp server.
can an ai agent open pull requests or leave reviews in github?
yes, through github's own mcp server rather than the connector. add it from the project's mcp marketplace with a github personal access token, and agents open pull requests, comment and review through mcp_call, acting as the token's owner. the connector pushes branches but never opens, reviews or comments on a pull request.
what does a github event notification contain?
the event routine, the actor, a one-line summary and a link, plus the event's own text where github sends it: the description of a new pull request or issue, the body of a comment, or the body of a review that approves or requests changes. that text is fenced off as untrusted data and capped at 4,000 characters.
is one github connection shared across my whole team?
no. github is connected inside a single project, and the credential is stored against that project. another project in the same team gets no github events and no git access until someone connects it there, so a client project cannot reach a repository that belongs to a different engagement.
what access does aldena ask github for?
every installation token aldena mints is narrowed to metadata read, contents write, pull requests read and issues read, whatever else the installation holds. contents write is what git push needs, and the two read grants let aldena check that a pull request or issue exists before an agent subscribes to it.
spin up your first project.
one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.
