At a glance
Cogno plugs into the repositories your team already works in. Connect GitHub and Cogno reads pull requests, issues, and commits as they happen, turns them into suggested tasks, and can carry out actions like merging a PR you’ve approved — without pulling you out of your normal workflow.
Before you start
- You have the Manage integrations permission in the target workspace.
- You can install a GitHub App on the target organization (or an org owner can approve it).
- You know which repositories Cogno should watch.
Connect GitHub in Cogno
1
Open the GitHub integration
Open Integrations and select GitHub.
2
Install the GitHub App
Click Add account. In the desktop app, Cogno opens the connection flow in your default browser. Complete the GitHub installation there.
3
Approve on GitHub
Choose the organization and approve the app. On GitHub you can grant all repositories or pick specific ones. If your org requires an owner’s approval, GitHub records a request and Cogno says so; once an owner approves, run Add account again to finish connecting.
4
Confirm the account
Back in Cogno, the account appears under GitHub accounts with its repository settings. Every connected account is listed on the same page. Use Add account to connect another organization or personal account.
Choose repositories
1
Open the account
Every connected account is listed under GitHub accounts, each with its own repositories, member mapping, and Issue import settings. The ⋯ menu on an account holds Disconnect.
2
Let the repo list sync
Under Repositories, Cogno pulls the list from the GitHub App installation on its own — when you open the account, and whenever GitHub grants access to more repositories than Cogno holds. Syncing repositories… shows while it runs.
3
Choose repositories
Use Search repositories to filter this account’s synced repositories by part of their name or owner, ignoring case. Clear the search with the × button or Esc to show the whole list again. Filtering does not change any repository’s on/off selection, including hidden repositories.Turn on the repositories Cogno should watch. Each change saves automatically; if saving fails, the switch returns to its previous state and an error appears.
Import Issues as Tasks
Expand Issue import settings. Under Issue import, turn import on for each repository where new open Issues should become Tasks, with each change saved automatically. Use Import existing to queue the repository’s current open Issues. Under Issue field mapping, select a repository, click Refresh values if needed, and map the values Cogno found to Cogno Task fields:- Issue state → Task status — the statuses on offer are Backlog, Ready, In Review, Done, and Archived (imported Issues never land directly in In Progress, which holds only queued or running work)
- Labels → Tags
- Assignees → Members
- Milestones → Projects
Map GitHub members to workspace members
On an organization installation’s page, expand Member mapping and link GitHub organization members to workspace members so GitHub activity is attributed to the right person. Choose Select member on a row, or choose Remove mapping from its menu to clear an existing match. Use Sync members to refresh the list. A personal GitHub installation has no member mappings — repository access still works.Sign in to your personal GitHub account
Open Account → Profile and choose Connect on the GitHub row. The desktop app opens your default browser; return to Cogno after signing in. The same row shows your GitHub username and Connected after confirmation. This personal sign-in applies across your Workspaces and is not configured on the Workspace integration page. The two settings have different jobs:
Member mapping includes a link to the Account settings. Disconnecting your personal account does not remove Workspace repository connections; disconnecting a repository connection does not sign you out of your personal GitHub account.
What Cogno does with GitHub
Review pull requests from a task
When a task has an open pull request, use Review under GitHub work to submit a comment, approve, or request changes. If a reviewer requests changes, Cogno summarizes the feedback on the task and loads the complete live list of unresolved inline threads, so every thread can be replied to or resolved in context. Use Files changed to load the pull request’s changed files, select an added, removed, or context line, and post a new inline comment. This is the direct path for giving the coding agent an exact file-and-line implementation instruction. Cogno checks the pull request’s latest head commit again before every review write. Inline comments are also checked against the live diff. If the PR changed after the task loaded, refresh the GitHub state and review the new head before submitting.Reviews, replies, and thread resolution are posted as the connected Cogno GitHub App. Pull request authors cannot approve their own pull requests, so an App-created PR must be approved by a human reviewer. GitHub repository rules also determine whether an App approval satisfies required-review protection.
What agents can do on GitHub
Engine-managed runs get GitHub tools for each GitHub connection. All four start allowed: Read GitHub, Publish to GitHub, Write to GitHub and Merge on GitHub. To have a person approve writes or merges first, choose Ask; an attended run then asks you, and an unattended run is refused. Under Agent tools on this page a workspace owner or admin sets each one for that exact connection — Block, Ask, or Allow — and a Project can narrow them further under Integrations in Project settings, where each row starts on the workspace value:
Agents in every Project can use every repository the connection reaches. To keep one Project’s agents to its own repositories, open the GitHub row under Integrations in Project settings and turn on Only this Project’s repositories under Repositories agents can use. The limit is saved as the list of repositories at that moment; if the Project’s repositories change later, choose Match this Project’s repositories to update it.
Read GitHub reads live from GitHub: a repository’s files, commits, code search, pull requests, and issues, in any repository the connection reaches — its selected repositories, or every repository the installation grants when none is selected. It also reads the Task’s own pull request — its changed files, reviews, inline review threads, and CI checks with the failure output and line annotations GitHub reported.
Publish to GitHub is how an agent delivers a code change. It commits to the branch Cogno reserved for the current Task, opens that Task’s pull request onto the repository’s base branch, rewrites its title and description, closes or reopens it, replies to or resolves its review threads, and re-runs failed GitHub Actions runs on its latest commit. Commits are made by the Cogno GitHub App, with the member who started the work as co-author when they linked their GitHub account. It can also pass a different base branch, and a run that has no Task opens a pull request from a branch it names, without recording it on any Task. Cogno no longer commits, pushes, or opens a pull request on its own after a run.
Write to GitHub opens issues, comments on issues and pull requests, and requests reviews in any repository the connection reaches.
Across all workspaces, agents are instructed to create GitHub issues, pull requests, comments, and reviews through Cogno’s GitHub tools as the connected GitHub App. This rule takes precedence over saved Skills or Project instructions that name a person’s
gh login. If the required tool, App permission, or approval is unavailable, the agent must report the blocker without switching to personal credentials or connectors. Local git commits and pushes remain available; this rule governs the identity used to create GitHub objects.
Merge on GitHub merges a pull request — the Task’s own, or one the agent names. Cogno refuses the merge unless the pull request is open, ready for review, free of conflicts, and every check on its latest commit has finished and passed. The merge is pinned to that commit, so a push that lands in between makes GitHub refuse it.
Include Slack images in an issue
Specify the destination private repository and the exact images to include when asking Cogno to create an issue from a Task. Cogno accepts up to 10 PNG, JPEG, GIF or WebP images, each at most 1 MiB, from Slack channels the Project can read. It does not automatically copy other images in the thread. Issue creation must be permitted. The destination connection must also allow GitHub publishing, and each source connection must allow Slack file reads. If either of these additional permissions is blocked or requires approval, attachment is refused; approval for issue creation alone does not authorize image transfer. If an image cannot be attached, Cogno does not create a text-only issue instead. An uncertain provider response stops automatic retries to prevent duplicate issues; check the repository before requesting another issue. Images already saved before a later failure remain in the repository.Manage or remove
- Manage permissions on GitHub opens the app’s installation settings on GitHub.
- Disconnect (then confirm in the dialog) removes the connection and all synced data (repositories and member mappings) for that installation.
Common states
Reference URLs
Related docs
- Integrations
- Work with Tasks
- Task statuses — how imported Issues map to statuses.
- Troubleshooting