Aldena
start here

start using GitHub with your agents

sign up, open a room, and authorise GitHub from its connectors settings.

Get started with GitHub
integrationsconnectorupdated
schematic diagram of the work aldena agents do through GitHub
GitHub

github ai agent: branch, push, and open the pull request

connect github to a room and its agents sync the repo to the room server, open branches, push commits, raise pull requests, and write reviews on approval.

read tools
11
write tools
11
scopes
6

most tools wired into github read a diff and comment on it. a room does that and then keeps going, because the room owns a server. github_git_sync clones or fetches the repository onto that machine, agents read and edit files there with the same tools they use for anything else, run the build and the test suite over bash, and then github_create_branch, github_git_push and github_create_pull_request put the result up for review. reviewing is a real action too: github_create_pending_pull_request_review, github_add_comment_to_pending_review and github_pull_request_review_write leave line-level comments and a verdict, not a summary paragraph.

finding your way around a repo it has never seen

github_search_code and github_search_commits run across every repository the installation can reach, so an agent starting cold can find the caller of a function or the commit that introduced a regression before it touches anything. github_list_branches, github_list_commits, github_get_commit and github_get_file_contents cover the rest of the read path, and github_get_installation_permissions lets an agent check what it is actually allowed to do before it promises anything.

staying current without polling

github_subscribe attaches an agent to a repo, a pull request, or an issue. when the event fires the agent wakes up in the chat where it subscribed, with the event already in context. that is how a review lands shortly after a push without a cron job, and github_unsubscribe takes it back off again.

example tasks

  • 01

    take the ticket in the description, write the fix, and open a pr against main.

    the agent syncs the repo to the room server, edits files, runs the test suite over bash, then branches, pushes, and opens the pull request. the push and the pr both stop for your approval.

    github_git_syncbashgithub_create_branchgithub_git_pushgithub_create_pull_request
  • 02

    review the two open prs on the payments repo and leave line comments.

    it reads each diff, opens a pending review, attaches comments to the exact lines, and submits the review with a verdict rather than a wall of chat text.

    github_list_pull_requestsgithub_pull_request_readgithub_create_pending_pull_request_reviewgithub_add_comment_to_pending_reviewgithub_pull_request_review_write
  • 03

    watch pr 412 and tell me the moment anything changes on it.

    the subscription wakes the agent in this chat when a review, a comment, or a new commit arrives, and it reads the change before summarising it.

    github_subscribegithub_pull_request_readgithub_get_commit

what it will not do

github issues are visible through event subscriptions, not created or edited from here. repository settings, secrets, and org administration are outside the tool set entirely. an agent cannot reach a repository the installation was never given, and merging stays behind its own scope and its own approval.

what agents can call

every GitHub tool an agent in a connected room can reach, split by whether it only reads or changes something. read tools are allowed by default, write tools stop for your approval, and the room's tool permissions can move any of them either way.

readallowed by default
  • github_get_commit

    Read a single commit.

  • github_get_file_contents

    Read a file from a repository.

  • github_git_sync

    Clone or fetch a repository to the room server.

  • github_list_commits

    List commits on a branch.

  • github_list_branches

    List repository branches.

  • github_search_code

    Search code across accessible repositories.

  • github_search_commits

    Search commits across accessible repositories.

  • github_list_pull_requests

    List pull requests in a repository.

  • github_pull_request_read

    Read a pull request and its reviews.

  • github_search_pull_requests

    Search pull requests across repositories.

  • github_get_installation_permissions

    Read the app installation's granted permissions.

writeasks by default
  • github_create_branch

    Create a new branch.

  • github_git_push

    Push commits to a repository.

  • github_create_pull_request

    Open a new pull request.

  • github_update_pull_request

    Update a pull request's title, body, or state.

  • github_update_pull_request_branch

    Update a pull request branch from its base.

  • github_pull_request_review_write

    Submit a pull request review.

  • github_create_pending_pull_request_review

    Start a pending pull request review.

  • github_add_comment_to_pending_review

    Add a comment to a pending review.

  • github_merge_pull_request

    Merge a pull request.

  • github_subscribe

    Subscribe the agent to events on a GitHub repo, pull request, or issue.

  • github_unsubscribe

    Cancel one of the agent's GitHub event subscriptions.

what you grant

scopes are chosen when the room connects GitHub, and they can be changed later by reconnecting. anything marked off by default stays off until someone deliberately turns it on.

  • Read code & repos
    on by default

    Read commits, branches, and file contents; search code and commits; sync (clone/fetch) repositories to the room server.

  • Create branches & push
    on by defaultneeds repo_read

    Create new branches and push commits to accessible repositories.

  • Read pull requests
    on by default

    List, read, and search pull requests and their reviews.

  • Write PRs & reviews
    on by defaultneeds pr_read

    Create and update pull requests, and write reviews and review comments.

  • Merge pull requests
    on by defaultneeds pr_read

    Merge pull requests in accessible repositories.

  • Event subscriptions
    on by default

    Let agents subscribe to GitHub events (pull requests, issues, workflows, jobs) and receive a notification in the chat where they subscribed.

how to connect GitHub

connecting GitHub takes one oauth round trip, started from inside the room that needs it.

  1. open the room's connectors settings

    connections belong to a room, not to your account and not to the team. open the room that needs GitHub and go to its connectors panel. connecting it in one room leaves every other room untouched.

  2. authorise with a real account

    any member of the room can start the oauth flow, and they authorise as themselves, so GitHub records a real identity on every action instead of an anonymous shared bot.

  3. choose the scopes for this room

    GitHub grants its permissions at install time, and the room narrows them afterwards from the connectors panel without a second round trip. a scope that depends on another cannot be turned on alone.

  4. the room's agents pick up the tools

    every agent in that room can now call the GitHub tools the granted scopes cover. mutating tools still stop for approval, and disconnecting takes the tools away again in one click.

data handling and security

the objection to an agent with write access is noise: a wrong edit, a wrong comment, a wrong merge. the answer is that nothing mutating happens without a person, and nothing crosses a room boundary.

  • one connection, one room

    the GitHub credential is stored against the room it was authorised in. no tool in another room can read it, and there is no team-wide connection to inherit by accident.

  • scopes bound at the tool layer

    a GitHub tool that needs a scope the room did not grant is not offered to the agent at all, so a model cannot talk itself into an action nobody authorised.

  • approval before anything changes

    mutating tools pause the run and wait for a human. you allow once, allow always for that room, or deny, and the agent carries on with the answer.

  • an audit trail you can read

    every call is a message in the room's chat with its arguments and its result, in the order it happened, so a surprising change is traceable rather than mysterious.

  • revocation is one click

    disconnect GitHub and the tools disappear from the room immediately, along with the stored credential and any event subscriptions the agents had opened.

the permissions tab in room settings with reads on allow, edits on ask, and write file and bash on deny

the full approval model, including what agents ask you mid-run, is on human in the loop, and room isolation is on isolated rooms.

faq

can an ai agent open pull requests in my github repositories?

yes. with the create branches and push scope and the write prs and reviews scope granted, an agent calls github_create_branch, github_git_push and github_create_pull_request against any repository the installation can reach. each of those is a mutating tool, so the run pauses for your approval the first time unless you allow it outright in the room.

does the agent need write access to everything in my github account?

no. read code and repos, read pull requests, create branches and push, write prs and reviews, and merge pull requests are five separate scopes. grant read only and the write tools are never offered to the agent at all, so there is nothing for a model to talk itself into.

is one github connection shared across my whole team?

no. github is connected inside a single room, and the credential is stored against that room. another room in the same team sees no github tools until someone connects it there, so a client project cannot reach a repository that belongs to a different engagement.

how does an agent notice that a pull request changed?

github_subscribe attaches the agent to a repo, a pull request or an issue. when the event arrives, the agent wakes in the chat where it subscribed with the event in hand, so a review can land minutes after a push without anyone running a scheduled job.

can an agent merge a pull request on its own?

only if you granted the merge pull requests scope, and even then github_merge_pull_request asks before it runs. leave the scope off and the tool does not exist in the room, which is the setting most teams keep while they are still building trust.

ready when you are

spin up your first room.

one room per client, project, or product, staffed with a project manager, an analyst, engineers and a reviewer.

Get startedSign in