Connect GitHub

Connect GitHub so squads can read repositories, push changes, and work with issues and pull requests. You need permission to manage integrations in Ficus and permission to authorize the account and install the GitHub App on the intended repositories.

Connect an account

Open Settings → Integrations, find GitHub, enable the card, and expand Settings. Choose Connect account.

Ficus Cloud

Follow the GitHub authorization page and return to your Ficus instance when it finishes. Cloud handles the shared OAuth application configuration; you do not need to enter an application client secret in your instance.

Self-hosted

The default setup uses Ficus’s GitHub App and device login, so no app setup is needed. Copy the code shown in Ficus, open the displayed GitHub verification link, and enter the code. Leave Ficus open while it waits for authorization. If the code expires, start Connect account again.

To use your own GitHub App, expand Use your own GitHub App in Settings, or Use your own GitHub App instead during onboarding. A client ID alone uses device login and needs no public URL; enable device flow in that App. Adding the optional client secret switches to browser authorization, which redirects to the exact callback URL displayed by Ficus. Enable expiring user tokens either way, and give the App the SSH signing keys account permission (read and write) so Ficus can sign agents’ commits.

If connecting fails, Ficus shows GitHub’s reason, such as GitHub being unreachable from the instance, device flow being disabled for the App, or GitHub rejecting the App’s client ID or secret. Fix the cause, then choose Retry.

Install the GitHub App on the repositories Ficus should use. Authorizing your user account alone does not give the App repository access. When you return, Ficus checks the App installations available to that account and how many repositories each installation exposes. If setup needs repository access, choose Grant repository access, install the App on the intended account or organization, and select its repositories. Return to Ficus or choose Check again to verify.

Access through an organization does not include forks owned by your personal account. Ficus shows a separate warning when the App is missing from that account. A failed or incomplete check is shown as unverified, rather than claiming the App is missing. The check verifies installation access, not whether a particular branch permits pushes.

Choose the squad’s account

The first connected account becomes the Global default. Squads inherit it unless they choose their own accounts or disable GitHub.

Open the squad’s Settings → Integrations.
Check that GitHub is enabled for the squad.
Keep the inherited account, or select the accounts this squad may use and its default identity.
For issue routing, enter the repository as owner/repository in GitHub Routing and add label filters if you want them. A pattern such as owner/* or owner/svc-* covers every matching repository the selected account can see (up to 100 per pattern); new repositories are picked up within ten minutes, and ones the account loses access to are dropped.

Repository routing and workflow subscriptions decide which updates a squad consumes. They do not grant repository access. The selected account and the App installation must both allow the operation.

Check that it works

Ask the squad to list the open pull requests in a repository it should access. Use a read-only request first, such as: “List the open pull requests in example-org/sample-app and summarize their titles.” Replace that example with your repository. Then continue with your first task.

Ficus uses the selected account when gh runs and when Git needs HTTPS credentials. Changing the connection takes effect for subsequent credential requests. Git commit author name and email are separate settings; edit those in Settings → Git or the squad’s author overrides when needed.

Receive repository updates

Ficus Cloud

Managed instances can receive shared-App webhook events when Cloud delivery is configured. You still need a squad account and a repository referenced by the squad’s work or subscriptions. You do not need to create a tenant webhook for that managed delivery path. Ficus also polls repositories referenced by its work.

Self-hosted

Polling works without a webhook. For direct delivery, expand Webhook delivery in the GitHub card. Copy its URL, generate or enter a signing secret, and configure the same secret in your GitHub App or repository webhook. Choose JSON delivery and the events your workflows consume, then save the setting in Ficus. Your instance must be reachable at the displayed public URL.

Keep a reviewer with a pull request

When a Review requested → Start work stream event rule creates work, Ficus uses the squad’s chosen workflow with PR review completion. The reviewer posts its review, then stays available for comments, new commits, and re-review requests. Finishing a review round does not finish the work stream: Ficus verifies that the pull request has merged or closed before allowing completion.

The stream can be parked to release capacity while keeping its reviewer and conversation. Incoming updates remain attached to the stream and wait for it to resume; parking does not create a replacement reviewer. A paused stream also retains updates until you resume it.

Existing active work streams keep priority over event-rule actions. If a new review request arrives after the original review stream has already completed or been canceled, Ficus notifies the squad manager to decide what to do next. It does not automatically reopen the stream or create another one. Duplicate webhook deliveries do not create duplicate notifications. Your account routing and GitHub author filter still apply.

Control who can send feedback to agents

Anyone who can comment on a public repository can write a pull request review or an issue comment. Before author filtering, every comment, review and inline comment that matched a squad’s routing or tracked work reached its agents. With author filtering on, Ficus holds feedback it can’t attribute to someone the squad trusts until a person reviews it.

Author filtering is on by default for new squads. Squads that existed before the feature start with it off, so raw routing does not apply author-trust checks until you turn it on. Version freshness is always enforced: once a newer version of the same GitHub object is known, a delayed older version is not delivered, even with author filtering off. This also applies to unaccepted inbox reads and queued parent quotations, not just automatic delivery. Ficus keeps an audit snapshot of dropped older events. Undelivered legacy GitHub prose without native object/version provenance is also withheld in every mode, including off; turning filtering off no longer restores those old unbound messages. This includes pre-upgrade queued off-mode review_requested, assigned, and labeled notifications: even if they identify the action itself, they lack the new rawParent binding for the issue or pull request text embedded in the message, so those in-flight notices will not be delivered after upgrade. Their audit reason is github_freshness_unbound. Ficus does not guess their identity or version or replay them. Already accepted messages and receipts remain history; other providers and proven content-free status facts are unchanged. New native-bound raw feedback still routes without author-trust checks when filtering is off. Turn it on or off in the squad’s Settings → Integrations under GitHub feedback review → Filter GitHub feedback by author. Leave it off only if every repository the squad watches is private to people you trust. When you turn it off, held events with readable content are allowed once and delivered to their current recipients; held events whose content can’t be read stay held until someone decides.

Trusted authors

A GitHub author is trusted in a squad when either of these is true:

Linked Ficus user. A Ficus user who can update the squad’s settings has linked their GitHub account in Settings → Account → GitHub account. Linking uses a GitHub sign-in to prove the account is yours. It does not connect repositories or give Ficus access to your account. This trust follows your current permission: if you lose the permission or unlink, your later feedback is held again.
Added manually. Someone who can update the squad added the account under Trusted authors. Use this for people and bots that have no Ficus account. Ficus looks the username up on GitHub and saves the numeric account ID, so trust keeps working after a rename and cannot be claimed by a new account that takes the old name.

The list shows every reason an author is trusted. Removing a manual entry does not remove trust that comes from a linked account. Bots are never trusted automatically, and GitHub’s author labels such as Member or Contributor do not count. Trust only decides whether feedback reaches agents; it never grants repository access or adds permissions.

What gets held

With author filtering on, Ficus checks who wrote or did each event:

Comments, reviews and inline comments are checked against their author. An edit also needs the person who edited it to be trusted.
Assignments, review requests, labels, and closing or reopening an issue are checked against the person who did it. They arrive as a short fixed message (who did what, the assignee or reviewer, the label and a link). An issue assignment or a review request also includes the issue or pull request’s current title and description, but only when the person who wrote it is trusted and Ficus can confirm the text is still theirs, so a trusted person assigning someone else’s issue doesn’t pass that issue’s text to agents. Ficus can confirm this when the issue or pull request hasn’t changed since it was opened, or when its title and description still match what its author wrote when Ficus received the opening event. GitHub doesn’t say who last edited a title or description, so text that may have been edited by someone else is left out. If the author stops being trusted before the message is delivered, agents get the short message instead.
New issues and pull requests are checked against their author.

Some events are held even when everyone involved is trusted, because Ficus can’t confirm who wrote or did them:

Edits to an issue or pull request title or description.
Events Ficus found by polling GitHub instead of receiving a webhook, when the event is a pull request review, an edit, an assignment, a label or a close/reopen. Polling doesn’t reliably tell Ficus who acted.
Events GitHub can’t confirm belong to the connected repository, events that arrive out of order, and content too large to review.

The review window shows the reason for each held event. Set up the repository webhook to keep these holds rare.

Screen untrusted feedback with a decision model

By default, feedback from people the squad doesn’t trust waits for a person. You can instead let a decision model look at it first. In GitHub feedback review → Feedback from untrusted authors, choose Screen with a model instead of Hold for review. This needs a decision model set up in Settings → Decision Providers.

With screening on, the model is asked whether the feedback contains instructions aimed at an agent reading it (such as ignoring its instructions, running commands, revealing secrets, changing permissions or contacting someone) and whether its intent is benign, suspicious or malicious:

When the model is confident the feedback is safe, Ficus delivers it once, the same way Allow once does. The author is still not trusted, so their next comment is screened again.
Anything else stays held for a person: feedback the model thinks may be unsafe or isn’t sure about, feedback too long to screen, and everything while no model is set up or the model doesn’t answer (Ficus asks again twice before giving up). The review window shows the model’s verdict, such as Decision model: likely prompt injection, 94%.

Screening applies to feedback that arrives after you choose it. To screen events that were already waiting, use Screen N waiting now (offered right after you switch, too). It screens up to 200 at a time. Events whose earlier screen got no answer, for example because no model was set up yet, are screened again; a verdict the model already gave is kept.

Screening only applies to feedback held because its author isn’t trusted. Events held for other reasons, such as an unverified editor or an event found by polling, always wait for a person. You can still allow or deny a held event while it’s being screened, and your decision wins; you can also deny feedback the model released until it reaches an agent. Choosing Hold for review again stops screens that haven’t finished. A decision model can be wrong, so use screening where an occasional unsafe comment reaching agents is acceptable.

Review held events

When events are held, Pending GitHub events appears on the squad’s Home and Work tabs with a count, and in the squad’s GitHub settings. Each of these opens the same Review GitHub events window. For each event it shows the author and why the event was held, the repository and pull request or issue, the intended recipient, and the exact text that will be delivered. It also links to the event on GitHub. Choose one or more events, then:

Allow once delivers exactly the version you reviewed. It does not trust the author.
Deny keeps the event out of every agent’s inbox. Ficus keeps a record of the decision.
Allow and trust author delivers the selected events and adds their authors as trusted authors of this squad. Their other held events stay held until you review them.

When Ficus captures a newer version of the same comment, review, issue or pull request, older pending versions become obsolete and leave the list automatically. Their audit records are kept, but those older versions are never delivered. Earlier delivery receipts do not authorize sending old text again. An action waiting to quote an issue or pull request is checked again before delivery: if the parent changed, the old quotation is withheld, even with author filtering off. An automatic action may be replaced with its trusted factual message alone if no recipient accepted it. A stale human-approved quotation returns as deny-only: it cannot be allowed again, even in a bulk approval or by turning filtering off. Its approval never silently transfers to a different message. Older quotations without enough parent provenance are also withheld.

With filtering off, a modern native-bound action whose parent goes stale instead gets an immutable factual-only variant for recipients who have not accepted the original. It contains no old or replacement parent prose and adds no author-trust check or approval. Recipients who already accepted keep their original message and receipt and get nothing new, including after retries or partial delivery. Original snapshots remain auditable as github_feedback_obsolete; the factual variant records github_factual_parent_obsolete. This does not rebind or replay pre-upgrade notices.

Allowed events are delivered by normal routing at the time you approve, so they reach whoever owns that work now. Paused or parked work receives them the usual way. A later edit on GitHub becomes a new version that is checked again; Ficus never delivers text you haven’t approved. The Releasing tab shows events that are waiting to be delivered or are retrying. An allowed event that keeps failing to deliver shows up with the pending events on Home and Work; you can deny it from there to stop the retries. If the squad’s GitHub connection can no longer read an event’s source, the review window hides the text and the event can only be denied.

Only people can review events, change trusted authors or turn filtering on or off, and they need permission to update the squad. Agents cannot do any of this, even when acting on a person’s behalf. People who can view the squad but not update it see the queue without the actions.

Pull request merges, closes and reopens and CI results still reach agents while feedback is held. They arrive as fixed status messages that include no titles, descriptions or log text. Dependabot alerts still arrive only through verified webhooks. Agents keep their usual tools, so an agent that runs gh or opens GitHub itself can still read anything the squad’s account can see. Author filtering controls what Ficus delivers and indexes; it does not make agents immune to untrusted text they fetch themselves.

Sign agents’ commits

Each account in the GitHub card has a Commit signing line. When it is on, commits and tags your agents make with that account are signed and show as Verified on GitHub. Connecting an account turns it on automatically; choose Turn on signing if it is off.

Ficus creates a signing key, adds it to the connected GitHub account (you can see it under GitHub Settings → SSH and GPG keys as Ficus commit signing), and keeps the private key on your Ficus server. Agents never see it: their git asks Ficus to sign each commit. Turn off removes the key from GitHub.

Signing needs the App’s SSH signing keys permission. If the card asks for it, choose Reconnect and approve the updated permissions on GitHub, then turn signing on. Commits show as Verified when the commit email is one GitHub has verified for the account; Ficus’s default, the account’s users.noreply.github.com address, always is.

Fix access or disconnect

If a repository cannot be read, check the App installation, the account’s repository permissions, and the squad assignment. If the card shows Reconnect required, choose Reconnect and authorize the intended account again.

If a push to your own fork is rejected, check that the App is installed on the fork as well as any upstream repository. Your account owning the fork does not automatically grant the App access. Pushes need Contents: write; changes to .github/workflows also need Workflows: write, which is separate from Actions: write. In GitHub’s installation settings, approve any pending App permission updates. Reconnecting in Ficus does not replace that approval or add repositories to the installation.

Disabling GitHub preserves saved accounts and assignments while stopping new use. Disconnecting removes access through Ficus and removes Ficus’s signing key from the account while the account’s authorization still allows it; without its private half, a leftover key cannot sign anything. Removing a default account does not silently choose another identity; select a new default explicitly. For full revocation, review GitHub Settings → Applications → Authorized GitHub Apps; public-client device authorizations cannot be remotely revoked by Ficus alone.