stouputils.continuous_delivery.github module#

This module contains utilities for continuous delivery on GitHub.

upload_to_github: Upload the project to GitHub using the credentials and the configuration (make a release and upload the assets, handle existing tag, generate changelog, etc.)

validate_credentials( credentials: dict[str, dict[str, str]], ) → tuple[str, dict[str, str]][source]#

Get and validate GitHub credentials

Parameters:

credentials (dict[str, dict[str, str]]) – Credentials for the GitHub API

Returns:

str: Owner (the username of the account to use)

dict[str, str]: Headers (for the requests to the GitHub API)

Return type:

tuple[str, dict[str, str]]

validate_config( github_config: dict[str, Any], ) → tuple[str, str, str, list[str]][source]#

Validate GitHub configuration

Parameters:

github_config (dict[str, str]) – Configuration for the GitHub project

Returns:

str: Project name on GitHub

str: Version of the project

str: Build folder path containing zip files to upload to the release

list[str]: List of zip files to upload to the release

Return type:

tuple[str, str, str, list[str]]

handle_existing_tag( owner: str, project_name: str, version: str, headers: dict[str, str], ) → bool[source]#

Check if tag exists and handle deletion if needed

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
version (str) – Version to check for existing tag
headers (dict[str, str]) – Headers for GitHub API requests

Returns:

True if the tag was deleted or if it was not found, False otherwise

Return type:

bool

delete_existing_release( owner: str, project_name: str, version: str, headers: dict[str, str], ) → None[source]#

Delete existing release for a version

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
version (str) – Version of the release to delete
headers (dict[str, str]) – Headers for GitHub API requests

delete_existing_tag( tag_url: str, headers: dict[str, str], ) → None[source]#

Delete existing tag

Parameters:

tag_url (str) – URL of the tag to delete
headers (dict[str, str]) – Headers for GitHub API requests

get_latest_tag( owner: str, project_name: str, version: str, headers: dict[str, str], ) → tuple[str, str] | tuple[None, None][source]#

Get latest tag information

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
version (str) – Version to remove from the list of tags
headers (dict[str, str]) – Headers for GitHub API requests

Returns:

SHA of the latest tag commit, None if no tags exist str|None: Version number of the latest tag, None if no tags exist

Return type:

str|None

get_commits_since_tag( owner: str, project_name: str, latest_tag_sha: str | None, headers: dict[str, str], ) → list[dict[str, Any]][source]#

Get commits since last tag

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
latest_tag_sha (str|None) – SHA of the latest tag commit
headers (dict[str, str]) – Headers for GitHub API requests

Returns:

List of commits since the last tag

Return type:

list[dict]

generate_changelog( commits: list[dict[str, Any]], owner: str, project_name: str, latest_tag_version: str | None, version: str, ) → str[source]#

Generate changelog from commits. They must follow the conventional commits convention.

Convention format: <type>: <description> or <type>(<sub-category>): <description>

Parameters:

commits (list[dict]) – List of commits to generate changelog from
owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
latest_tag_version (str|None) – Version number of the latest tag
version (str) – Current version being released

Returns:

Generated changelog text

Return type:

str

Source:: https://www.conventionalcommits.org/en/v1.0.0/

create_tag( owner: str, project_name: str, version: str, headers: dict[str, str], ) → None[source]#

Create a new tag

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
version (str) – Version for the new tag
headers (dict[str, str]) – Headers for GitHub API requests

create_release( owner: str, project_name: str, version: str, changelog: str, headers: dict[str, str], ) → int[source]#

Create a new release

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
version (str) – Version for the new release
changelog (str) – Changelog text for the release
headers (dict[str, str]) – Headers for GitHub API requests

Returns:

ID of the created release

Return type:

int

upload_assets( owner: str, project_name: str, release_id: int, build_folder: str, headers: dict[str, str], endswith: list[str], ) → None[source]#

Upload release assets

Parameters:

owner (str) – GitHub username
project_name (str) – Name of the GitHub repository
release_id (int) – ID of the release to upload assets to
build_folder (str) – Folder containing assets to upload
headers (dict[str, str]) – Headers for GitHub API requests
endswith (list[str]) – List of files to upload to the release (every file ending with one of these strings will be uploaded)

upload_to_github( credentials: dict[str, Any], github_config: dict[str, Any], ) → str[source]#

Upload the project to GitHub using the credentials and the configuration

Parameters:

credentials (dict[str, Any]) – Credentials for the GitHub API
github_config (dict[str, Any]) – Configuration for the GitHub project

Returns:

Generated changelog text

Return type:

str

Examples:

> upload_to_github(
        credentials={
                "github": {
                        "api_key": "ghp_...",
                        "username": "Stoupy"
                }
        },
        github_config={
                "project_name": "stouputils",
                "version": "1.0.0",
                "build_folder": "build",
                "endswith": [".zip"]
        }
)