Install & Compatibility
Where this runs
tested against v0.4.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 6.922s · 264.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 22.0s · import 6.416s · 264MB
259MB installed
● package 259MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GitHubCredentials
✓ from prefect_github import GitHubCredentials
✗ from prefect_github.credentials import GitHubCredentials
While technically correct, the top-level import is more common and often sufficient, as GitHubCredentials is exposed directly by the package.
query_repository
✓ from prefect_github.repository import query_repository
add_star_starrable
✓ from prefect_github.mutations import add_star_starrable
GitRepository
✓ from prefect.runner.storage import GitRepository
Used in Prefect deployments to specify code location, often in conjunction with GitHubCredentials for private repos.
This quickstart demonstrates how to authenticate with GitHub using `GitHubCredentials` and perform a GraphQL query to get repository details, followed by attempting to add a star to a repository. Ensure you have a GitHub Personal Access Token (PAT) with appropriate scopes (e.g., `public_repo` or `repo`) set as an environment variable named `GITHUB_PAT`.
import os
from prefect import flow
from prefect_github import GitHubCredentials
from prefect_github.repository import query_repository
from prefect_github.mutations import add_star_starrable
@flow(log_prints=True)
def github_interaction_flow():
# It's recommended to store tokens securely, e.g., in Prefect Blocks
# and load them by name. For a quickstart, we use an env var.
github_token = os.environ.get('GITHUB_PAT', 'YOUR_GITHUB_TOKEN')
if github_token == 'YOUR_GITHUB_TOKEN' or not github_token:
print("Please set the GITHUB_PAT environment variable or replace 'YOUR_GITHUB_TOKEN' with a valid GitHub Personal Access Token.")
return
# Create a GitHubCredentials block (or load an existing one)
github_credentials = GitHubCredentials(token=github_token)
# Optionally save the block for re-use in the Prefect UI or other flows:
# github_credentials.save(name="my-github-pat", overwrite=True)
print(f"Querying repository details for PrefectHQ/prefect...")
repository_info = query_repository(
owner="PrefectHQ",
name="prefect",
github_credentials=github_credentials,
return_fields="id name url", # Request specific fields
)
print(f"Repository Name: {repository_info.get('name')}")
print(f"Repository URL: {repository_info.get('url')}")
repository_id = repository_info.get("id")
if repository_id:
print(f"Attempting to add a star to {repository_info.get('name')} (ID: {repository_id})...")
# Note: Starring requires a PAT with 'public_repo' or 'repo' scope
# This action might fail if the token doesn't have sufficient permissions
# or if the repository is already starred by the user associated with the token.
try:
starrable_status = add_star_starrable(
starrable_id=repository_id,
github_credentials=github_credentials,
)
print(f"Star operation successful: {starrable_status.get('starrable', {}).get('viewerHasStarred')}")
except Exception as e:
print(f"Failed to add star: {e}")
else:
print("Could not retrieve repository ID.")
if __name__ == "__main__":
github_interaction_flow()
Debug
Known issues
breakingActive development for `prefect-github` has been moved into the main `PrefectHQ/prefect` repository. Future features and fixes will be applied there. Users seeking to contribute or report issues should target the main Prefect repository.fixFor contributions or issue reporting, use the PrefectHQ/prefect repository on GitHub instead of the `prefect-github` repository.
affects: <=0.4.2
gotcha`prefect-github` is designed to work with Prefect 2.x. While Prefect 3.0 is in release candidate, specific compatibility nuances for `prefect-github` with Prefect 3.x might exist or require different integration patterns.fixIf upgrading to Prefect 3.x, consult the latest Prefect documentation for integration best practices. Test existing workflows thoroughly after upgrading Prefect core.
affects: All versions of prefect-github (0.x.x)
gotchaTo use `GitHubCredentials` blocks (or any other block type) with Prefect, they must be registered. If you create blocks via code, ensure the `prefect_github` module is registered, or save the block explicitly. Without registration, `GitHubCredentials.load()` might fail.fixRun `prefect block register -m prefect_github` in an environment connected to your Prefect API. Alternatively, save blocks explicitly in your code using `github_credentials.save(name='your-block-name')`.
affects: All versions
gotchaAccessing private GitHub repositories or performing mutations requires a GitHub Personal Access Token (PAT). This token must be configured correctly within a `GitHubCredentials` block and have the necessary scopes. Using hardcoded tokens is discouraged.fixStore your GitHub PAT securely in a `GitHubCredentials` block (created via UI or code) and load it by name within your flows. Ensure the PAT has the appropriate scopes (e.g., `repo` for full control, `public_repo` for public repo actions, `read:org` for organization access).
affects: All versions
gotchaWhen using Prefect workers to pull code from private GitHub repositories, `prefect-github` must be installed within the worker's execution environment, and the worker must be configured to connect to the same Prefect API where the `GitHubCredentials` block is stored.fixEnsure `pip install prefect-github` is part of your worker image/environment setup. Verify `PREFECT_API_URL` and `PREFECT_API_KEY` are correctly configured for the worker to access your Prefect server or Cloud instance.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prefect_github'
The `prefect-github` library is not installed in the Python environment where the Prefect flow or worker is attempting to run.
fixpip install prefect-github
RuntimeError: Failed to clone repository 'https://github.com/OWNER/REPO.git' with exit code 128.
This error typically indicates a problem with Git authentication or permissions when Prefect attempts to clone a repository, often due to an invalid or missing GitHub Personal Access Token (PAT) in the `GitHubCredentials` block, or insufficient permissions for the PAT on the target repository.
fixEnsure your `GitHubCredentials` block is configured with a valid Personal Access Token (PAT) that has the necessary read/write scopes for the repository. When defining your deployment's pull steps, ensure the `credentials` argument correctly references your saved `GitHubCredentials` block, and the `repository` URL is the full HTTPS clone URL. Example of a `prefect.yaml` pull step:
```yaml
pull:
- prefect.deployments.steps.git_clone:
repository: https://github.com/PrefectHQ/prefect-github.git
branch: main
credentials: "{{ prefect.blocks.github-credentials.my-github-pat-block-name }}"
``` Authentication failed
This message, often seen in Prefect UI or logs when interacting with GitHub-related tasks, indicates that the `GitHubCredentials` block is using an invalid, expired, or improperly scoped Personal Access Token (PAT), or the block itself was not correctly saved or loaded.
fixVerify the GitHub Personal Access Token used in your `GitHubCredentials` block is active and has the required scopes (e.g., 'repo' or 'public_repo' for public access, broader scopes for private repo actions). Re-save the `GitHubCredentials` block in Prefect if necessary, using `github_credentials.save("your-block-name", overwrite=True)` after instantiation, and ensure it's correctly loaded in your flow. ValidationError: 1 validation error for GitHubRepository repository_url Field required
This `ValidationError` occurs when creating or configuring a `GitRepository` object or a `git_clone` step, where the essential `repository` or `repository_url` argument is missing or incorrectly specified, usually by not providing the full HTTPS URL of the GitHub repository.
fixProvide the complete HTTPS URL of the GitHub repository to the `repository` or `url` argument. For example, instead of 'owner/repo', use 'https://github.com/owner/repo.git'.
```python
from prefect.runner.storage import GitRepository
from prefect_github import GitHubCredentials
github_credentials = GitHubCredentials(token="YOUR_GITHUB_PAT") # Assume PAT is loaded or from env
git_repo = GitRepository(
url="https://github.com/PrefectHQ/prefect-github.git", # Correct: Full HTTPS URL
branch="main",
credentials=github_credentials,
)
``` Upgrade
Version history
0.4.4latest on PyPI · released Jun 12, 2026
Audit
Dependencies
prefectrequiredCore orchestration framework; prefect-github is an integration designed to work with Prefect 2.x.