Skip to main content
connic
Connectors

GitHub

Start agents from issues, comments, and pull requests in your repositories, and post their results as comments or new issues.

Last updated
ModesInbound, outbound
YAML typegithub
CredentialsA Connection of type github, with a GitHub App that connic prepares and you create on GitHub
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedEvents get 200 and start no runs. Outbound sends nothing.

Set up

  1. In Project Settings → Connections, click New connection and choose GitHub. You can also create the Connection from the Connection picker in the connector form.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

FieldTypeStatusDescription
typestringRequiredgithub.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a GitHub Connection whose setup is complete. Dashboard: Connection.
configobjectRequiredGitHub settings.
repositorystringRequiredInbound 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.
eventsstring[]RequiredInbound. 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.

ValueModesDescription
Webhook URLInbound, outboundWhere 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 manifestInbound, outboundThe GitHub App definition with its permissions and events. Create on GitHub sends it to GitHub.
App ID, private key, webhook secretInbound, outboundGitHub 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:

payload.json
{
  "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": { ... }
}
  • event and action are GitHub's event name and action, such as issue_comment and created.
  • number is the issue or pull request number, and title its title, also for comments and reviews.
  • conversation_id stays the same for every event of one issue or pull request. To give the agent the earlier comments as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • text is the body of the issue, pull request, comment, or review, and url the link to it.
  • sender is the GitHub login of the person who caused the event.
  • raw is 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:

  1. When the output or payload sets issue_number, it comments on that issue or pull request in the connector's repository.
  2. 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.
  3. Otherwise it opens an issue in the connector's repository. The title is title from 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.

output.json
{
  "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.

connector-payload.json
{
  "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

LimitValue
App name34 characters, unique on GitHub
App setupWithin one hour of starting on GitHub
Answer to GitHubGitHub expects an answer within 10 seconds. connic answers right away and runs the agents afterwards.
Failed deliveriesGitHub 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 length65,536 characters per comment or issue, set by GitHub. A longer body isn't sent.
Comments and issuesAbout 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.