Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# semantic_release.hvcs.github module

Helper code for interacting with a GitHub remote VCS

class semantic_release.hvcs.github.Github(remote_url: str, *, hvcs_domain: str | None = None, hvcs_api_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **_kwargs: Any)

  Bases: `RemoteHvcsBase`

  GitHub HVCS interface for interacting with GitHub repositories

  This class supports the following products:

  > - GitHub Free, Pro, & Team

  > - GitHub Enterprise Cloud

  > - GitHub Enterprise Server (on-premises installations)

  This interface does its best to detect which product is configured based on the provided domain. If it is the official github.com, the default domain, then it is considered as GitHub Enterprise Cloud which uses the subdomain api.github.com for api communication.

  If the provided domain is anything else, than it is assumed to be communicating with an on-premise or 3rd-party maintained GitHub instance which matches with the GitHub Enterprise Server product. The on-prem server product uses a path prefix for handling api requests which is configured to be server.domain/api/v3 based on the documentation in April 2024.

  DEFAULT_API_DOMAIN = 'api.github.com'
  DEFAULT_API_PATH_CLOUD = '/'
  DEFAULT_API_PATH_ONPREM = '/api/v3'
  DEFAULT_API_SUBDOMAIN_PREFIX = 'api'
  DEFAULT_API_URL_CLOUD = 'https://api.github.com'
  DEFAULT_DOMAIN = 'github.com'
  DEFAULT_ENV_TOKEN_NAME = 'GH_TOKEN'
  OFFICIAL_NAME = 'GitHub'
  asset_upload_url(release_id: str) → str | None

    Get the correct upload url for a release https://docs.github.com/en/enterprise-server@3.5/rest/releases/releases#get-a-release :param release_id: ID of the release to upload to :return: URL to upload for a release if found, else None

  commit_hash_url(commit_hash: str) → str
  compare_url(from_rev: str, to_rev: str) → str

    Get the GitHub comparison link between two version tags. :param from_rev: The older version to compare. :param to_rev: The newer version to compare. :return: Link to view a comparison between the two versions.

  create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → int

    Post release changelog :param tag: The version number :param release_notes: The release notes for this version :param prerelease: Whether or not this release should be created as a prerelease :return: The status of the request

  create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None, noop: bool = False) → int

    Create a new release

    REF: https://docs.github.com/rest/reference/repos#create-a-release

    Parameters:

      - tag – Tag to create release for

      - release_notes – The release notes for this version

      - prerelease – Whether or not this release should be created as a prerelease

      - assets – a list of artifacts to upload to the release

    Returns:

      the ID of the release

  create_release_url(tag: str = '') → str
  edit_release_notes(release_id: int, release_notes: str) → int

    Edit a release with updated change notes https://docs.github.com/rest/reference/repos#update-a-release :param release_id: ID of release to update :param release_notes: The release notes for this version :return: The ID of the release that was edited

  static format_w_official_vcs_name(format_str: str) → str
  get_changelog_context_filters() → tuple[Callable[..., Any], ...]

    Return a list of functions that can be used as filters in a Jinja2 template

    ex. filters to convert text to URLs for issues and commits

  get_release_id_by_tag(tag: str) → int | None

    Get a release by its tag name https://docs.github.com/rest/reference/repos#get-a-release-by-tag-name :param tag: Tag to get release for :return: ID of release, if found, else None

  issue_url(issue_num: str | int) → str
  pull_request_url(pr_number: str | int) → str
  remote_url(use_token: bool = True) → str

    Get the remote url including the token for authentication if requested

  upload_dists(tag: str, dist_glob: str) → int

    Upload distributions to a release :param tag: Version to upload for :param dist_glob: Path to the dist directory :return: The number of distributions successfully uploaded

  upload_release_asset(release_id: int, file: str, label: str | None = None) → bool

    Upload an asset to an existing release https://docs.github.com/rest/reference/repos#upload-a-release-asset :param release_id: ID of the release to upload to :param file: Path of the file to upload :param label: Optional custom label for this file :return: The status of the request