{"id":5374,"library":"prefect-github","title":"Prefect GitHub","description":"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.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-github","tags":["prefect","github","workflow","orchestration","integration","block","credentials","devops"],"install":[{"cmd":"pip install prefect-github","lang":"bash","label":"Install prefect-github"}],"dependencies":[{"reason":"Core orchestration framework; prefect-github is an integration designed to work with Prefect 2.x.","package":"prefect","optional":false}],"imports":[{"note":"While technically correct, the top-level import is more common and often sufficient, as GitHubCredentials is exposed directly by the package.","wrong":"from prefect_github.credentials import GitHubCredentials","symbol":"GitHubCredentials","correct":"from prefect_github import GitHubCredentials"},{"symbol":"query_repository","correct":"from prefect_github.repository import query_repository"},{"symbol":"add_star_starrable","correct":"from prefect_github.mutations import add_star_starrable"},{"note":"Used in Prefect deployments to specify code location, often in conjunction with GitHubCredentials for private repos.","symbol":"GitRepository","correct":"from prefect.runner.storage import GitRepository"}],"quickstart":{"code":"import os\nfrom prefect import flow\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.repository import query_repository\nfrom prefect_github.mutations import add_star_starrable\n\n@flow(log_prints=True)\ndef github_interaction_flow():\n    # It's recommended to store tokens securely, e.g., in Prefect Blocks\n    # and load them by name. For a quickstart, we use an env var.\n    github_token = os.environ.get('GITHUB_PAT', 'YOUR_GITHUB_TOKEN')\n    if github_token == 'YOUR_GITHUB_TOKEN' or not github_token:\n        print(\"Please set the GITHUB_PAT environment variable or replace 'YOUR_GITHUB_TOKEN' with a valid GitHub Personal Access Token.\")\n        return\n\n    # Create a GitHubCredentials block (or load an existing one)\n    github_credentials = GitHubCredentials(token=github_token)\n    # Optionally save the block for re-use in the Prefect UI or other flows:\n    # github_credentials.save(name=\"my-github-pat\", overwrite=True)\n\n    print(f\"Querying repository details for PrefectHQ/prefect...\")\n    repository_info = query_repository(\n        owner=\"PrefectHQ\",\n        name=\"prefect\",\n        github_credentials=github_credentials,\n        return_fields=\"id name url\", # Request specific fields\n    )\n    print(f\"Repository Name: {repository_info.get('name')}\")\n    print(f\"Repository URL: {repository_info.get('url')}\")\n    repository_id = repository_info.get(\"id\")\n\n    if repository_id:\n        print(f\"Attempting to add a star to {repository_info.get('name')} (ID: {repository_id})...\")\n        # Note: Starring requires a PAT with 'public_repo' or 'repo' scope\n        # This action might fail if the token doesn't have sufficient permissions\n        # or if the repository is already starred by the user associated with the token.\n        try:\n            starrable_status = add_star_starrable(\n                starrable_id=repository_id,\n                github_credentials=github_credentials,\n            )\n            print(f\"Star operation successful: {starrable_status.get('starrable', {}).get('viewerHasStarred')}\")\n        except Exception as e:\n            print(f\"Failed to add star: {e}\")\n    else:\n        print(\"Could not retrieve repository ID.\")\n\nif __name__ == \"__main__\":\n    github_interaction_flow()","lang":"python","description":"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`."},"warnings":[{"fix":"For contributions or issue reporting, use the PrefectHQ/prefect repository on GitHub instead of the `prefect-github` repository.","message":"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.","severity":"breaking","affected_versions":"<=0.4.2"},{"fix":"If upgrading to Prefect 3.x, consult the latest Prefect documentation for integration best practices. Test existing workflows thoroughly after upgrading Prefect core.","message":"`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.","severity":"gotcha","affected_versions":"All versions of prefect-github (0.x.x)"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}