GitHub Provider

The GitHub provider fetches files, directory listings, issues, and pull requests from GitHub repositories. It uses the GitHub API for all operations and supports automatic staleness detection.

Quick Start

The GitHub provider works without configuration. Pass the repository as the first argument:

{{ colin.github.file("PrefectHQ/prefect", "README.md").content }}
{{ colin.github.issue("PrefectHQ/prefect", 123).title }}
{{ colin.github.pr("https://github.com/PrefectHQ/prefect/pull/456").state }}

For frequently accessed repositories, configure named instances to avoid repeating the repo:

{{ colin.github.prefect.file("README.md").content }}
{{ colin.github.prefect.issue(123).title }}

Configuration

Named instances are optional but useful for repositories you access frequently or that require authentication:

colin.toml

[[providers.github]]
name = "prefect"
repo = "PrefectHQ/prefect"
token = "${GITHUB_TOKEN}"

Field	Required	Description
`name`	Yes	Provider instance name for template access
`repo`	Yes	Repository in `owner/repo` format
`token`	No	GitHub token for private repos and higher rate limits

Each configured repository becomes accessible as colin.github.{name} in templates.

Multiple Repositories

Configure multiple repositories as separate provider instances:

colin.toml

[[providers.github]]
name = "prefect"
repo = "PrefectHQ/prefect"

[[providers.github]]
name = "docs"
repo = "PrefectHQ/prefect-docs"
token = "${GITHUB_TOKEN}"

Access each by name:

{{ colin.github.prefect.file("README.md") }}
{{ colin.github.docs.file("index.md") }}

Authentication

Without a token, requests are subject to GitHub’s anonymous rate limit (60 requests per hour). With a token, the limit increases to 5,000 requests per hour. For private repositories, a token with appropriate permissions is required.

Template Functions

Function	Purpose
`file()`	Fetch a file’s content
`ls()`	List directory contents
`issue()`	Fetch a single issue
`pr()`	Fetch a single pull request
`issues()`	List issues with filters
`prs()`	List pull requests with filters

file()

Fetch a file from a repository. Without configuration, pass the repo as the first argument:

{# Default provider: repo as first argument #}
{{ colin.github.file("PrefectHQ/prefect", "README.md").content }}
{{ colin.github.file("owner/repo", "src/main.py", ref="v1.0").content }}

{# Named instance: repo pre-configured #}
{{ colin.github.prefect.file("README.md").content }}
{{ colin.github.prefect.file("src/prefect/flows.py", ref="main").content }}

Default provider arguments:

Argument	Required	Default	Description
`repo`	Yes	—	Repository in `owner/repo` format
`path`	Yes	—	File path in the repository
`ref`	No	`"HEAD"`	Git ref (branch, tag, or commit SHA)
`watch`	No	`True`	Track for staleness detection

Named instance arguments (repo already configured):

Argument	Required	Default	Description
`path`	Yes	—	File path in the repository
`ref`	No	`"HEAD"`	Git ref (branch, tag, or commit SHA)
`watch`	No	`True`	Track for staleness detection

Returns a GitHubFileResource with the file content.

ls()

List directory contents. Without configuration, pass the repo as the first argument:

{# Default provider: repo as first argument #}
{% for entry in colin.github.ls("PrefectHQ/prefect", "src/prefect/") %}
- {{ entry.name }} ({{ entry.type }})
{% endfor %}

{# Named instance: repo pre-configured #}
{% for entry in colin.github.prefect.ls("src/prefect/") %}
- {{ entry.name }} ({{ entry.type }})
{% endfor %}

Default provider arguments:

Argument	Required	Default	Description
`repo`	Yes	—	Repository in `owner/repo` format
`path`	No	`""`	Directory path (empty for root)
`ref`	No	`"HEAD"`	Git ref (branch, tag, or commit SHA)
`watch`	No	`True`	Track for staleness detection

Named instance arguments (repo already configured):

Argument	Required	Default	Description
`path`	No	`""`	Directory path (empty for root)
`ref`	No	`"HEAD"`	Git ref (branch, tag, or commit SHA)
`watch`	No	`True`	Track for staleness detection

Returns a GitHubListingResource that can be iterated to get entries.

issue()

Fetch a single issue by number or URL:

{# By number with repo #}
{{ colin.github.issue("owner/repo", 123).title }}

{# By number with configured repo #}
{{ colin.github.prefect.issue(123).content }}

{# By full URL #}
{{ colin.github.issue("https://github.com/owner/repo/issues/123").state }}

Arguments:

Argument	Required	Default	Description
`number_or_url`	Yes	—	Issue number or full GitHub URL
`repo`	No	—	Repository in `owner/repo` format (required if using number without configured repo)
`watch`	No	`True`	Track for staleness detection

Returns a GitHubIssueResource with the issue content and metadata.

pr()

Fetch a single pull request by number or URL:

{# By number with repo #}
{{ colin.github.pr("owner/repo", 456).title }}

{# By number with configured repo #}
{{ colin.github.prefect.pr(456).head_ref }}

{# By full URL #}
{{ colin.github.pr("https://github.com/owner/repo/pull/456").state }}

Arguments:

Argument	Required	Default	Description
`number_or_url`	Yes	—	PR number or full GitHub URL
`repo`	No	—	Repository in `owner/repo` format (required if using number without configured repo)
`watch`	No	`True`	Track for staleness detection

Returns a GitHubPRResource with the PR content and metadata.

issues()

List issues with optional filters:

{# Open issues in configured repo #}
{% for issue in colin.github.prefect.issues() %}
- #{{ issue.number }}: {{ issue.title }}
{% endfor %}

{# Filtered issues #}
{% for issue in colin.github.issues("owner/repo", state="open", labels=["bug"]) %}
{{ issue.title }} ({{ issue.assignees | join(", ") or "unassigned" }})
{% endfor %}

Arguments:

Argument	Required	Default	Description
`repo`	No	—	Repository in `owner/repo` format (uses configured repo if None)
`state`	No	`"open"`	Filter by state: `"open"`, `"closed"`, or `"all"`
`labels`	No	`None`	Filter by label names
`assignee`	No	`None`	Filter by assignee username
`limit`	No	`30`	Maximum number of issues
`watch`	No	`True`	Track for staleness detection

Returns a GitHubIssuesResource that can be iterated.

prs()

List pull requests with optional filters:

{# Open PRs in configured repo #}
{% for pr in colin.github.prefect.prs() %}
- #{{ pr.number }}: {{ pr.title }} ({{ pr.head_ref }} -> {{ pr.base_ref }})
{% endfor %}

{# PRs targeting main #}
{% for pr in colin.github.prs("owner/repo", state="open", base="main") %}
{{ pr.title }} - {{ pr.state }}
{% endfor %}

Arguments:

Argument	Required	Default	Description
`repo`	No	—	Repository in `owner/repo` format (uses configured repo if None)
`state`	No	`"open"`	Filter by state: `"open"`, `"closed"`, or `"all"`
`base`	No	`None`	Filter by base branch
`head`	No	`None`	Filter by head branch
`limit`	No	`30`	Maximum number of PRs
`watch`	No	`True`	Track for staleness detection

Returns a GitHubPRsResource that can be iterated.

Objects

GitHubFileResource

Returned by file():

Property	Type	Description
`content`	`str`	File content
`path`	`str`	File path in the repository
`repo`	`str`	Repository in `owner/repo` format
`git_ref`	`str`	Original git ref
`resolved_sha`	`str`	Resolved commit SHA

GitHubListingResource

Returned by ls():

Property	Type	Description
`content`	`str`	Newline-separated list of paths
`entries`	`list[GitHubEntry]`	Directory entries
`path`	`str`	Directory path
`tree_sha`	`str`	Tree SHA for versioning

Supports iteration:

{% for entry in colin.github.prefect.ls("src/") %}
{{ entry.name }}
{% endfor %}

GitHubEntry

Each entry in a directory listing:

Property	Type	Description
`path`	`str`	Full path from repository root
`name`	`str`	Filename only
`type`	`str`	`"file"` or `"dir"`
`sha`	`str`	Blob or tree SHA
`size`	`int \| None`	File size in bytes (None for directories)

GitHubIssueResource

Returned by issue():

Property	Type	Description
`content`	`str`	Issue title and body as markdown
`repo`	`str`	Repository in `owner/repo` format
`number`	`int`	Issue number
`title`	`str`	Issue title
`body`	`str \| None`	Issue body (markdown)
`state`	`str`	`"open"` or `"closed"`
`labels`	`list[str]`	Label names
`assignees`	`list[str]`	Assignee usernames
`author`	`str \| None`	Username of creator
`url`	`str`	HTML URL to issue
`updated_at`	`datetime`	Last update time
`created_at`	`datetime`	Creation time
`closed_at`	`datetime \| None`	When closed (None if open)
`comments_count`	`int`	Number of comments

GitHubPRResource

Returned by pr():

Property	Type	Description
`content`	`str`	PR title and body as markdown
`repo`	`str`	Repository in `owner/repo` format
`number`	`int`	PR number
`title`	`str`	PR title
`body`	`str \| None`	PR body (markdown)
`state`	`str`	`"open"`, `"closed"`, or `"merged"`
`labels`	`list[str]`	Label names
`assignees`	`list[str]`	Assignee usernames
`author`	`str \| None`	Username of creator
`url`	`str`	HTML URL to PR
`head_ref`	`str`	Source branch name
`base_ref`	`str`	Target branch name
`head_sha`	`str`	Current head commit SHA
`is_draft`	`bool`	Whether PR is a draft
`updated_at`	`datetime`	Last update time
`created_at`	`datetime`	Creation time
`closed_at`	`datetime \| None`	When closed
`merged_at`	`datetime \| None`	When merged
`additions`	`int`	Lines added
`deletions`	`int`	Lines deleted
`changed_files`	`int`	Files changed

GitHubIssuesResource

Returned by issues():

Property	Type	Description
`content`	`str`	Newline-separated issue summaries
`issues`	`list[GitHubIssueResource]`	List of issue resources

Supports iteration and len():

{% for issue in colin.github.prefect.issues(labels=["bug"]) %}
#{{ issue.number }}: {{ issue.title }}
{% endfor %}

GitHubPRsResource

Returned by prs():

Property	Type	Description
`content`	`str`	Newline-separated PR summaries
`prs`	`list[GitHubPRResource]`	List of PR resources

Supports iteration and len():

{% for pr in colin.github.prefect.prs(state="open") %}
#{{ pr.number }}: {{ pr.title }}
{% endfor %}

Dependency Tracking

By default, all methods automatically track dependencies (watch=True). Documents recompile when tracked resources change:

{# Automatically tracked — recompiles when file changes #}
{{ colin.github.prefect.file("README.md").content }}

{# Automatically tracked — recompiles when issue is updated #}
{{ colin.github.prefect.issue(123).title }}

{# Opt out of tracking with watch=False #}
{{ colin.github.prefect.issue(123, watch=False).title }}

Issues and PRs are tracked by their updated_at timestamp. Any edit to the issue (title, body, labels, comments, etc.) triggers recompilation. Collections like issues() and prs() track all items collectively:

{# Recompiles when any issue in the list is updated #}
{% for issue in colin.github.prefect.issues(labels=["bug"]) %}
- #{{ issue.number }}: {{ issue.title }}
{% endfor %}

Staleness Detection

The GitHub provider uses different versioning strategies for different resource types: Files and directories resolve git refs to commit SHAs:

Ref Type	Behavior
Branch (`main`)	Resolves to tip SHA; recompiles when branch advances
Tag (`v1.0`)	Resolves to tagged commit SHA; stable unless tag is moved
SHA (`abc123`)	Immutable; never triggers recompilation

Issues and PRs use their updated_at timestamp. Any modification (edits, comments, label changes, state changes) triggers recompilation. Collections (issues(), prs()) compute a hash of all item numbers and their update times. Changes to any item in the list, or items entering/leaving the list, trigger recompilation.

Error Handling

Status	Exception	Description
404	`FileNotFoundError`	Ref, path, or file not found
401	`PermissionError`	Authentication required (private repo)
403	`PermissionError`	Rate limited or access denied

Examples

Include External Documentation

Pull documentation from another repository:

models/external-docs.md

---
name: External Docs
---

# API Reference

{{ colin.github.prefect.file("docs/api/flows.md", ref="main").content }}

Generate Index from Directory

Create an index of example files:

models/examples-index.md

---
name: Examples Index
---

# Examples

{% for entry in colin.github.prefect.ls("examples/") %}
{% if entry.type == "file" and entry.name.endswith(".py") %}
## {{ entry.name }}

```python
{{ colin.github.prefect.file(entry.path).content }}
```

{% endif %}
{% endfor %}

Pin to a Specific Version

Reference files from a tagged release:

models/v3-config.md

---
name: V3 Configuration
---

Configuration for Prefect v3.0.0:

```python
{{ colin.github.prefect.file("src/prefect/settings.py", ref="v3.0.0").content }}

### Quick Access Without Configuration

Fetch files from any repository without pre-configuring it:

```jinja models/any-repo.md
---
name: External Reference
---

# License from another repo

{{ colin.github.file("anthropics/claude-code", "LICENSE").content }}

Track an Issue

Create a document that updates when an issue changes:

models/tracked-issue.md

---
name: Feature Request Status
---

{% set issue = colin.github.prefect.issue(123) %}
# {{ issue.title }}

**Status:** {{ issue.state }}
**Labels:** {{ issue.labels | join(", ") or "none" }}
**Assignees:** {{ issue.assignees | join(", ") or "unassigned" }}

{{ issue.body }}

Bug Dashboard

Generate a dashboard of open bugs:

models/bug-dashboard.md

---
name: Bug Dashboard
---

# Open Bugs

{% for issue in colin.github.prefect.issues(labels=["bug"], state="open") %}
## #{{ issue.number }}: {{ issue.title }}

- **Author:** {{ issue.author }}
- **Created:** {{ issue.created_at.strftime("%Y-%m-%d") }}
- **Comments:** {{ issue.comments_count }}

{{ issue.body[:200] }}{% if issue.body and issue.body|length > 200 %}...{% endif %}

{% endfor %}

PR Status Report

Track open PRs and their review status:

models/pr-status.md

---
name: Open PRs
---

# Pull Requests

{% for pr in colin.github.prefect.prs(state="open", base="main") %}
- **#{{ pr.number }}**: {{ pr.title }}
  - Branch: `{{ pr.head_ref }}` -> `{{ pr.base_ref }}`
  - Changes: +{{ pr.additions }}/-{{ pr.deletions }} in {{ pr.changed_files }} files
  {% if pr.is_draft %}(Draft){% endif %}
{% endfor %}

Get Started

Projects

Providers

Renderers

Running Colin

GitHub Provider

Quick Start

Configuration

Multiple Repositories

Authentication

Template Functions

file()

ls()

issue()

pr()

issues()

prs()

Objects

GitHubFileResource

GitHubListingResource

GitHubEntry

GitHubIssueResource

GitHubPRResource

GitHubIssuesResource

GitHubPRsResource

Dependency Tracking

Staleness Detection

Error Handling

Examples

Include External Documentation

Generate Index from Directory

Pin to a Specific Version

Track an Issue

Bug Dashboard

PR Status Report

Get Started

Projects

Providers

Renderers

Running Colin

​Quick Start

​Configuration

​Multiple Repositories

​Authentication

​Template Functions

​file()

​ls()

​issue()

​pr()

​issues()

​prs()

​Objects

​GitHubFileResource

​GitHubListingResource

​GitHubEntry

​GitHubIssueResource

​GitHubPRResource

​GitHubIssuesResource

​GitHubPRsResource

​Dependency Tracking

​Staleness Detection

​Error Handling

​Examples

​Include External Documentation

​Generate Index from Directory

​Pin to a Specific Version

​Track an Issue

​Bug Dashboard

​PR Status Report

Quick Start

Configuration

Multiple Repositories

Authentication

Template Functions

file()

ls()

issue()

pr()

issues()

prs()

Objects

GitHubFileResource

GitHubListingResource

GitHubEntry

GitHubIssueResource

GitHubPRResource

GitHubIssuesResource

GitHubPRsResource

Dependency Tracking

Staleness Detection

Error Handling

Examples

Include External Documentation

Generate Index from Directory

Pin to a Specific Version

Track an Issue

Bug Dashboard

PR Status Report