Registry / workflow / prefect-github

prefect-github

JSON →
library0.4.4pypypi✓ verified 24d ago

Prefect-github provides Prefect integrations for interacting with GitHub. It includes a `GitHubCredentials` block for secure authentication using Personal Access Tokens (PATs) and various utilities to interact with GitHub repositories, such as cloning, querying repository details, and performing mutations (e.g., adding stars, creating issues). The tasks within this collection were initially generated using the GitHub GraphQL schema. While the standalone `prefect-github` package is currently at version 0.4.2, active development for this integration has been merged into the main PrefectHQ/prefect repository, which follows its own release cadence.

pip install prefect-github
INSTALL
IMPORT
SIG · PREFECT-GITHUB
P
prefect-github
workflowpythonv0.4.4
Install
22.0s avg
Import
6669ms
Disk
259MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 6.922s · 264.3MB
glibc
py 3.103.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.
fix
For 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.
fix
If 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.
fix
Run `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.
fix
Store 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.
fix
Ensure `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.
fix
pip 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.
fix
Ensure 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.
fix
Verify 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.
fix
Provide 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.
Agent activity
25 hits · last 30 days
node
20
OpenAI (training)
1
Resources
prefect-github — pip install prefect-github · libregistry