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)[source]#

Bases: HvcsBase

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_DOMAIN = 'github.com'#

DEFAULT_ENV_TOKEN_NAME = 'GH_TOKEN'#

asset_upload_url(release_id: str) → str | None[source]#: 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[source]#: Given a commit hash, return a web URL which links to this commit in the remote VCS.

compare_url(from_rev: str, to_rev: str) → str[source]#: 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_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str[source]#

create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → int[source]#: Post release changelog :param version: The version number :param release_notes: The release notes for this version :return: The status of the request

create_release(tag: str, release_notes: str, prerelease: bool = False) → int[source]#: Create a new release https://docs.github.com/rest/reference/repos#create-a-release :param tag: Tag to create release for :param release_notes: The release notes for this version :param prerelease: Whether or not this release should be created as a prerelease :return: the ID of the release

create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str[source]#

edit_release_notes(release_id: int, release_notes: str) → int[source]#: Edit a release with updated change notes https://docs.github.com/rest/reference/repos#update-a-release :param id: ID of release to update :param release_notes: The release notes for this version :return: The ID of the release that was edited

get_release_id_by_tag(tag: str) → int | None[source]#: 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

pull_request_url(pr_number: str | int) → str[source]#: Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool = True) → str[source]#: Get the remote url including the token for authentication if requested

upload_asset(release_id: int, file: str, label: str | None = None) → bool[source]#: 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

upload_dists(tag: str, dist_glob: str) → int[source]#: Upload distributions to a release :param version: Version to upload for :param path: Path to the dist directory :return: The number of distributions successfully uploaded