Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect a GitHub token (Issues) to Fondoo

Live4 min readUpdated

This connection lets your AI agent read and open issues in one GitHub repository. For example, it can file a bug report from a customer conversation or check which issues are still open. It uses a fine-grained personal access token limited to that repository and to issues only. Code changes do not go through this connection; they use the separate GitHub App connection (provider github).

What Fondoo can do with it

ActionWhat it doesGitHub call
issues.list (read)Lists issues in the repository. You can filter by state (open, closed, all) and page through with page and per_pageGET /repos/{owner}/{repo}/issues
issues.create (write)Opens a new issue from the fields you supply, such as title and bodyPOST /repos/{owner}/{repo}/issues

Your agent calls them with:

  • connector_action({connectionId, action:"issues.list", input:{state:"open"}})
  • connector_action({connectionId, action:"issues.create", input:{data:{title:"…", body:"…"}}})

Things to know:

  • GitHub treats every pull request as an issue too, so issues.list also returns pull requests. You can tell them apart by the pull_request field (Issues API).
  • Neither action is destructive or spends money, so neither needs owner approval.
  • Agents need Fondoo's connectors:read scope to list and connectors:write scope to create. Every call is audited.
  • There is no edit, close or delete action.

Before you start

  • A GitHub account with access to the repository. You must be able to create issues there.
  • Organization rules. If the repository belongs to an organization, it may require approval for fine-grained tokens, or block them entirely. A token waiting for approval can only read public resources until an organization admin approves it (managing personal access tokens).
  • The repository's owner and name, for example owner acme and repo website.
  • There is no GitHub cost for API use.

Step by step: get your credentials

  1. On GitHub, click your profile picture → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
  2. Fill in Token name (for example "Fondoo issues") and an optional Description.
  3. Choose an Expiration. A shorter lifetime is safer. Fondoo can remind you before it runs out (see "Rotate" below).
  4. Set Resource owner to the user or organization that owns the repository. An organization that blocks fine-grained tokens will not appear in this list.
  5. Under Repository access, choose Only select repositories and pick the one repository.
  6. Under Permissions → Repository permissions, set Issues to Read and write. GitHub also includes Metadata as read-only. Leave every other permission at No access (required permissions).
  7. Click Generate token and copy it. GitHub shows it only once.

Connect it in Fondoo

In the dashboard:

  1. Open Connections and type "GitHub" in Find a tool. Two GitHub cards may appear under Development. The token connection is the one with a Use a key button; the other one is the GitHub App.
  2. Click Use a key → Open secure key entry.
  3. Fill in apiKey (the token), owner and repo.
  4. Click Save connection securely. The link lasts 15 minutes and works once.
  5. Click Check connection.

By asking your agent. For example:

"Connect our GitHub repo acme/website so you can open issues for bugs customers report."

The agent calls add_connection_key({provider:"github_token", siteId}) without fields and sends you the secure link. Never paste the token in chat: tokens sent in fields trigger a chat-log warning. connect_service({provider:"github_token", siteId}) returns a signed 15-minute instruction link. Then the agent runs test_connection({connectionId}).

REST: POST https://api.getfondoo.com/v1/ops/add_connection_key with Authorization: Bearer <your Fondoo key> and {"provider":"github_token","siteId":"<site UUID>"}.

Test that it works

  1. test_connection calls GET /user. Status connected means GitHub accepts the token. It does not yet prove repository access, so issues.list and issues.create show as "unknown".
  2. Ask your agent to list open issues. If it returns results (or an empty list) without an error, the repository permissions are right.
  3. Optionally, have it open a test issue, then close it yourself on GitHub.

Troubleshooting

  • Status invalid or "Provider request failed (401)". The token is wrong, expired or revoked. Generate a new one.
  • "Provider request failed (404)" when listing. The owner or repo is misspelled, or the token was not given that repository. GitHub returns 404 rather than 403 for private repositories you cannot see.
  • "Provider request failed (403)" when creating. Issues is not set to Read and write, the organization has not approved the token yet, or issues are disabled on the repository.
  • Pull requests show up in the list. This is expected; see above.
  • "Provider request failed (429)" or 403 with a rate-limit message. GitHub allows 5,000 requests per hour per token, plus secondary limits such as 80 content-creating requests per minute (rate limits). Fondoo also limits each connection to about 60 actions per minute.

Limits, data and security

  • What Fondoo stores: the encrypted token, owner and repo, status, last test and last use. list_connections shows [redacted]. Issue contents are returned to the caller and not stored.
  • Rotate: set expiresAt (and optionally rotateAfter) when adding the key, and Fondoo reminds you a week before. To replace the token, generate a new one, call rotate_connection_key({connectionId}) without fields, and paste it. Fondoo blocks use of an expired credential.
  • Disconnect: delete_connection({connectionId}) removes the token from Fondoo. Agents need your approval. Then delete the token under Fine-grained tokens on GitHub.