Buffaly Logo
Browse docs Menu

Start here

Docs home Install Buffaly Install on Windows Install on Linux Install on Mac Quickstart How-to library

Learn Buffaly

What Buffaly is User guide Core concepts Coming from other agents Memory and skills

Build and extend

Add a prompt skill Add a ProtoScript skill Add a C# DLL tool Add a model provider Skills, services, and tools ProtoScript services

Operate

Sessions and long-running work Session anatomy Plan, Scratch, and Tasks Session artifacts Session timeline Compaction

Reference

Ontology and ProtoScript Providers and authentication Web modules and UI Diagnostics & recovery Safety rules Secrets handling SmartPatch
Integration how-to

How to connect GitHub to Buffaly

For a first GitHub setup, make sure the machine running Buffaly can use GitHub CLI. Then verify read-only repository access before asking Buffaly to remember repository names or work with issues, pull requests, and code changes.

Do not paste GitHub passwords, personal access tokens, app private keys, or OAuth secrets into normal chat. Use a documented secret-backed flow if this install needs token-based authentication.

Why GitHub CLI comes first

Buffaly can remember repository names without GitHub access, but it cannot safely inspect private repositories, issues, or pull requests until the machine has a working authenticated GitHub path. GitHub CLI is the easiest first path because you can test it outside Buffaly.

Not installed

Install GitHub CLI, restart Buffaly if needed, then verify gh --version.

Installed, not signed in

Run gh auth login in a visible terminal. It is interactive and may wait for browser input.

Already authenticated

Continue to read-only repository checks before using Buffaly for GitHub work.

Verify read-only access

Use a harmless read before asking Buffaly to use GitHub. A good first verification checks authentication, repository metadata, and optionally a short issue or pull request list.

gh --version
gh auth status
gh repo view <owner>/<repo> --json name,owner,defaultBranchRef,visibility
gh issue list --repo <owner>/<repo> --limit 5
gh pr list --repo <owner>/<repo> --limit 5
  • gh auth status should show a logged-in account.
  • gh repo view should return the expected repository name, owner, branch, and visibility.
  • Issue and PR checks should work for the repositories Buffaly will use.

Teach Buffaly what repository names mean

Repository memory and GitHub access are separate. After access works, teach Buffaly the names and aliases you use so future requests bind to the right repository.

Example: “Remember that customer portal means the GitHub repository https://github.com/acme/customer-portal. It is the source repo for the customer-facing portal. Use the alias portal repo too.”

Buffaly should summarize what it is about to remember and ask for confirmation before saving durable memory.

Decide what GitHub access should allow

GoalNeeded accessFirst verification
Remember repository namesNo GitHub credentialBuffaly repeats the correct URL and aliases.
Read private repositoriesAuthenticated gh or another configured integrationgh repo view succeeds.
Read issues or pull requestsAuthenticated GitHub path with repo permissionsgh issue list or gh pr list succeeds.
Create branches, comments, issues, or PRsWrite-capable path plus explicit confirmationRead-only checks pass first; write action is approval-gated.

Other connection patterns can include a GitHub MCP service binding, GitHub App or OAuth integration, or a token stored through Buffaly's secrets/settings flow. Do not assume any of these exist until the live install verifies them.

Step-by-step screenshots to capture later

For a visual walkthrough, capture screenshots of the terminal showing gh --version, gh auth status, a successful gh repo view, Buffaly remembering the repository alias, and Buffaly verifying a harmless read-only GitHub request.

Step 1–5 and other GitHub connection patterns

  1. Step 1: check whether gh is installed and visible to the account running Buffaly.
  2. Step 2: sign in with gh auth login in a visible terminal if needed.
  3. Step 3: verify read-only repository access with gh repo view.
  4. Step 4: tell Buffaly what repository names and aliases mean.
  5. Step 5: ask Buffaly to verify the setup before authorizing write actions.

Other GitHub connection patterns can include a GitHub MCP service binding, a GitHub App or OAuth integration, or a token stored through Buffaly's secret-backed configuration path. Treat those as install-specific capabilities and ask Buffaly to verify they exist before relying on them.

How to tell it worked

  • Buffaly can run or delegate harmless repository reads for the expected repository.
  • Repository aliases bind to the right owner/repo instead of a guessed label.
  • Issue and pull request reads work when those workflows are needed.
  • Buffaly asks before write actions such as branch creation, comments, issue updates, or pull requests.

Common problems

GitHub login seems stuck

Run gh auth login yourself in a visible terminal. Hidden background processes can wait forever for browser or terminal input.

GitHub CLI works in your terminal but not in Buffaly

Restart the Buffaly process after installing gh so it receives the updated PATH. Also verify the account running Buffaly can see the same installation.

Public repositories work but private repositories fail

The authenticated account may lack repository access or scopes. Verify manually with gh repo view <owner>/<repo>.

Buffaly remembers the repo but cannot read issues

Memory tells Buffaly what a name means. GitHub access still requires an authenticated tool or service binding.

After it works

Ask Buffaly to remember your GitHub workflow: use GitHub CLI, check gh auth status, verify the repo with gh repo view, start with read-only issue and PR checks, and ask before creating branches, commits, comments, labels, or pull requests.