Prefect GitHub

Warnings

• breaking Active 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.
• 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.
• gotcha To 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')`.
• gotcha Accessing 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).
• gotcha When 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.

Install

• pip install prefect-github Install prefect-github

Imports

• GitHubCredentials

  from prefect_github 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.

Quickstart

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()