GitHub
Start agents from issues, comments, and pull requests in your repositories, and post their results as comments or new issues.
On this page
| Modes | Inbound, outbound |
| YAML type | github |
| Credentials | A Connection of type github, with a GitHub App that connic prepares and you create on GitHub |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A matching event starts every linked agent. |
| While paused | Events get 200 and start no runs. Outbound sends nothing. |
Set up
In Project Settings → Connections, click New connection and choose GitHub. You can also create the Connection from the Connection picker in the connector form.
Under Name, enter a name for the Connection and the GitHub App name, which comments and issues from your agents show. To create the app in an organization, enter it under Organization; leave the field empty for your personal account. Click Create connection.
Under Create app, click Create on GitHub. GitHub shows the app connic prepared, and you can still change its name there. Create the app. GitHub sends you back to the Connections page, where connic finishes the setup by itself.
Under Install, click Install on GitHub, choose the account or organization, and pick the repositories the agents should work in. You can add repositories later on GitHub. Click Done.
Open the agent. In Connector Flow, click Add inbound connector for repository events or Add outbound connector for comments and issues. Then click Create New Connector and choose GitHub.
Choose the mode, Inbound (Repository events) or Outbound (Comments and issues), and pick the Connection under Connection. Enter the Repository as owner/name, such as
acme/api, and for inbound the Events. Click Create. For outbound, then choose how the agent uses the connector and click Link connector.
Configuration
The fields of a GitHub connector, the same in connectors/*.yaml, the REST API, and connic MCP. The GitHub Connection they name must have finished its setup in the dashboard; until then, the deploy or request fails. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | github. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Inbound and outbound. Name or ID of a GitHub Connection whose setup is complete. Dashboard: Connection. |
| config | object | Required | GitHub settings. |
| repository | string | Required | Inbound and outbound. The repository as owner/name, such as acme/api. Inbound connectors receive its events, and outbound connectors open issues there. The GitHub App must be installed on it before you create the connector; see GitHub App. Dashboard: Repository. |
| events | string[] | Required | Inbound. The events that start runs. Each entry is an event, such as issues, for all its actions, or event.action for one action only, such as issues.opened, issue_comment.created, or pull_request.closed. Events: issues, issue_comment, pull_request, pull_request_review, and pull_request_review_comment. Dashboard: Events, one per line, starting with issues.opened. |
The GitHub App, its private key, and its webhook secret belong to the Connection, not to the connector.
Generated values
connic generates these on the Connection, so every connector that uses the Connection shares them.
| Value | Modes | Description |
|---|---|---|
| Webhook URL | Inbound, outbound | Where GitHub sends the app's events, one URL per Connection. connic puts it into the app manifest, so you don't enter it anywhere. |
| App manifest | Inbound, outbound | The GitHub App definition with its permissions and events. Create on GitHub sends it to GitHub. |
| App ID, private key, webhook secret | Inbound, outbound | GitHub hands them to connic when it creates the app, so you don't paste anything. |
Agent input
Modes: Inbound
An inbound connector starts a run for every linked agent each time a matching event happens in its repository. Events the app causes itself, such as its own comments and issues, are ignored, so agents don't trigger themselves. The run receives:
{
"event": "issue_comment",
"action": "created",
"repository": "acme/api",
"number": 42,
"conversation_id": "github:acme/api#42",
"title": "Checkout fails for EUR orders",
"text": "Still happening on main after the last deploy.",
"url": "https://github.com/acme/api/issues/42#issuecomment-2481190311",
"sender": "octocat",
"raw": { ... }
}eventandactionare GitHub's event name and action, such asissue_commentandcreated.numberis the issue or pull request number, andtitleits title, also for comments and reviews.conversation_idstays the same for every event of one issue or pull request. To give the agent the earlier comments as history, setsession.key: input.conversation_idin its YAML; the connector doesn't turn on sessions by itself.textis the body of the issue, pull request, comment, or review, andurlthe link to it.senderis the GitHub login of the person who caused the event.rawis GitHub's full event payload as sent.
Several connectors can watch the same repository, for example one for issues and one for pull requests, or one per environment. An event reaches every connector whose repository and events match. An event that GitHub delivers again with the same delivery ID doesn't start another run. Inbound mode doesn't reply by itself: to comment on the issue or pull request, link the agent to an outbound GitHub connector that uses the same Connection; see Outbound delivery.
GitHub App
Create on GitHub sends connic's app manifest to GitHub. It describes a private GitHub App with the repository permissions Issues (read and write), Pull requests (read and write), and Metadata (read). The app subscribes to the events issues, issue_comment, pull_request, pull_request_review, and pull_request_review_comment at the Connection's webhook URL. After you create the app, GitHub sends you back to the Connections page, and connic finishes the setup with the app's ID, private key, and webhook secret. This has to happen within one hour of starting on GitHub.
The app name has at most 34 characters and must be unique on GitHub; you can change it on GitHub before you create the app. Leave Organization empty to create the app on your personal account. To create it in an organization, you need to be an owner of that organization.
The app is private, so only the account that owns it can install it. Create one Connection per GitHub account or organization. A Connection serves any number of inbound and outbound connectors in every environment. connic checks the signature of every event from GitHub with the webhook secret.
Install the app on the repository a connector names before you create the connector; connic checks this and tells you when the app isn't installed there. You can add repositories to the installation later on GitHub.
Outbound delivery
Modes: Outbound
An outbound GitHub connector posts once each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides where:
- When the output or payload sets
issue_number, it comments on that issue or pull request in the connector's repository. - When the run came in through a GitHub inbound connector on the same Connection, it comments on the issue or pull request the run started from.
- Otherwise it opens an issue in the connector's repository. The title is
titlefrom the output or payload, or else the first line of the text.
Automatic output
An automatic link posts the run's final output. Plain text becomes the body. A JSON object takes the body from body, text, message, response, or output, in that order, and can set title and issue_number.
{
"title": "EUR totals are rounded twice at checkout",
"body": "Orders in EUR are one cent off since 2.14.0. The total is rounded in the cart and again at payment."
}Agent-tool and middleware payload
The model or middleware passes body, which is required and can't be empty, and optionally title and issue_number. Other fields are rejected.
{
"body": "Reproduced on main: the total is rounded in the cart and again at payment.",
"issue_number": 42
}Delivery and retries
When GitHub rate-limits a comment or issue, connic waits and sends it again. The connector's runs show each delivery with the link to the comment or issue, or with the error.
Limits and errors
| Limit | Value |
|---|---|
| App name | 34 characters, unique on GitHub |
| App setup | Within one hour of starting on GitHub |
| Answer to GitHub | GitHub expects an answer within 10 seconds. connic answers right away and runs the agents afterwards. |
| Failed deliveries | GitHub doesn't retry them. Redeliver them for up to 3 days from the app's Advanced settings on GitHub or through GitHub's API. |
| Body length | 65,536 characters per comment or issue, set by GitHub. A longer body isn't sent. |
| Comments and issues | About 80 per minute under GitHub's secondary rate limit. When GitHub rate-limits, connic waits and retries the delivery. |
Requests with a missing or wrong signature get 401. Creating a connector fails while the Connection's setup isn't complete or when the app isn't installed on the repository. A delivery fails when GitHub rejects it, for example when the issue doesn't exist or the app can't write issues in the repository.