Connect GitHub

GitHub is a built-in shared connection with the id github. One token covers two things:

• Plugins. Cengrid reads plugin and marketplace repositories with it. See connect capabilities from GitHub.
• Agent work. Anyone in the connection’s scope can have the agent clone, push and open pull requests, without a personal GitHub connection.

The definition fixes the endpoints: REST calls go to https://api.github.com and Git remotes live under https://github.com.

Create the organisation connection

1. In GitHub, create a fine-grained personal access token, ideally owned by a service account, limited to the repositories Cengrid should see. For plugins alone, read-only access to those repositories is enough. For agent work, add contents write and pull request write on the repositories where the agent should push.
2. In the admin console, open Connections, select Organisation, and configure GitHub.
3. Paste the token and enable the connection. New connections start read-only, which is all plugin imports need. To let the agent push and open pull requests, turn Read-only off, and under advanced settings optionally add write rules limiting which repositories it may push to.
4. Save, then choose Test connection. For GitHub, Cengrid calls /rate_limit. A Working result means the token is accepted.

If you try to connect a plugin before this exists, the Plugins page sends you here with the GitHub configuration ready to edit.

Plugin access rules

Plugin repositories, marketplaces, Re-sync and app file fetches all use the enabled GitHub connection at the Organisation scope, for public and private repositories alike. Personal GitHub sign-ins, team connections and other service credentials are never used. Every administrator uses the same connection, and Git credentials are never stored in plugin records.

Team overrides

A team can add its own GitHub connection with the same github id, which takes precedence for that team’s rooms, and for its members’ direct messages when it is their primary team. A disabled team connection does not fall back to the organisation’s. A team connection is used for agent work only. Plugin imports always use the organisation connection.

Write limits

Choose read-only to allow clone and fetch and refuse push. Otherwise you can add write rules that restrict pushes to named repositories. Git rules are relative to https://github.com, so pushing to org/repo needs a POST rule for /org/repo, while REST writes use /repos/org/repo. Details are in connections.

Let people connect their own account

An organisation can also register a GitHub OAuth app so individuals connect their own accounts from their Keychain. That is a separate, optional route and is not used for plugins.