GitHub

The GitHub provider syncs tasks (issues) and repositories from configured GitHub projects into the local filesystem. Repositories are cloned via SSH and kept up to date with git fetch. Pull requests are excluded from tasks.

Configuration

Set interactively via banco provider add.

Parameter	Required	Description
`api_key`	yes	GitHub personal access token
`host`	no	GitHub instance URL (default: `https://github.com`) — set for GitHub Enterprise Server
`projects`	no †	Explicit list of project paths in `owner/repo` format
`projects_pattern`	no †	Regex matched against `owner/repo` — e.g. `myorg/.*`
`namespaced`	no	Clone into the full `owner/repo` path instead of a flat leaf dir (default: `false`)

† Exactly one of projects or projects_pattern must be set; they are mutually exclusive.

The GitHub provider implements two modules, tasks and repos. Turn either off with the top-level disabled_modules field — e.g. disabled_modules: [repos] to sync issues only.

Example configuration

providers:
  - name: github
    config:
      api_key: $GITHUB_TOKEN
      projects:
        - myorg/my-project
        - myorg/another-project

With a pattern and GitHub Enterprise:

providers:
  - name: github
    alias: github-work
    config:
      api_key: $GITHUB_WORK_TOKEN
      host: https://github.mycompany.com
      projects_pattern: myorg/.*

Directory structure

Tasks are synced flat under tasks/<provider>/<owner>/<repo>/:

tasks/
└── github/
    └── myorg/
        └── my-project/
            └── 0042 - Fix login bug.md

Repos are cloned under repos/<provider>/. By default the layout is flat — each repo is cloned into a directory named after the repo (repos/github/<repo>/). Set namespaced: true to clone into the full owner/repo path (repos/github/<owner>/<repo>/), which avoids collisions when owners share a repo name.

Task file format

Each task file carries a YAML frontmatter block followed by the issue title and description:

---
status: open
tags:
  - bug
---

# Fix login bug

Description here...

status is open or closed. tags mirrors the issue’s labels on GitHub. Both fields are updated automatically on each banco sync without touching the rest of the file.

Templates

New task files are initialized from the first matching template found under .banco/templates/tasks/: github/<owner>/<repo>/TEMPLATE.md → github/<owner>/TEMPLATE.md → github/TEMPLATE.md → tasks/TEMPLATE.md. See Templates for details.

Sync

After a successful sync, banco stores the timestamp in .banco/sync-state/<provider>. On every sync, all currently-open issues are fetched.

After writing the fetched issues, banco reconciles local tasks: any local task with status: open whose issue number was not in the fetched set is marked closed — it was closed on GitHub and disappeared from the open results. Tasks already closed locally are left untouched.

See banco sync for the full sync flow.

Keyboard shortcuts