Coverage for pyVersioning/GitHub.py: 73%

1# ==================================================================================================================== # 

2# __ __ _ _ # 

3# _ __ _ \ \ / /__ _ __ ___(_) ___ _ __ (_)_ __ __ _ # 

4# | '_ \| | | \ \ / / _ \ '__/ __| |/ _ \| '_ \| | '_ \ / _` | # 

5# | |_) | |_| |\ V / __/ | \__ \ | (_) | | | | | | | | (_| | # 

6# | .__/ \__, | \_/ \___|_| |___/_|\___/|_| |_|_|_| |_|\__, | # 

7# |_| |___/ |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2020-2025 Patrick Lehmann - Bötzingen, Germany # 

15# # 

16# Licensed under the Apache License, Version 2.0 (the "License"); # 

17# you may not use this file except in compliance with the License. # 

18# You may obtain a copy of the License at # 

19# # 

20# http://www.apache.org/licenses/LICENSE-2.0 # 

21# # 

22# Unless required by applicable law or agreed to in writing, software # 

23# distributed under the License is distributed on an "AS IS" BASIS, # 

24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

25# See the License for the specific language governing permissions and # 

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31"""GitHub specific code to collect the build environment.""" 

32from os import environ 

33from typing import Optional as Nullable 

34 

35from pyTooling.Decorators import export 

36from pyTooling.Exceptions import ToolingException 

37from pyTooling.GenericPath.URL import URL 

38 

39from pyVersioning.CIService import CIService, Platform, ServiceException 

40 

41 

42@export 

43class GitHub(CIService): 

44 """Collect Git and other platform and environment information from environment variables provided by GitHub Actions.""" 

45 

46 ENV_INCLUDE_FILTER = ("GITHUB_", ) #: List of environment variable name pattern for inclusion. 

47 ENV_EXCLUDE_FILTER = ("_TOKEN", ) #: List of environment variable name pattern for exclusion. 

48 ENV_INCLUDES = ("CI", ) #: List of environment variable to include. 

49 ENV_EXCLUDES = () #: List of environment variable to exclude. 

50 

51 def GetPlatform(self) -> Platform: 

52 return Platform("github") 

53 

54 def GetGitHash(self) -> str: 

55 """ 

56 Returns the Git hash (SHA1 - 160-bit) as a string. 

57 

58 :return: Git hash as a hex formated string (40 characters). 

59 :raises ServiceException: If environment variable ``GITHUB_SHA`` was not found. 

60 """ 

61 try: 

62 return environ["GITHUB_SHA"] 

63 except KeyError as ex: 

64 raise ServiceException(f"Can't find GitHub Action environment variable 'GITHUB_SHA'.") from ex 

65 

66 def GetGitBranch(self) -> Nullable[str]: 

67 """ 

68 Returns Git branch name or ``None`` is not checked out on a branch. 

69 

70 :return: Git branch name or ``None``. 

71 :raises ServiceException: If environment variable ``GITHUB_REF`` was not found or reference doesn't start with ``refs/heads/``. 

72 """ 

73 branchPrefix = "refs/heads/" 

74 

75 try: 

76 ref = environ["GITHUB_REF"] 

77 if ref.startswith(branchPrefix): 77 ↛ 82line 77 didn't jump to line 82 because the condition on line 77 was always true

78 return ref[len(branchPrefix):] 

79 except KeyError: 

80 return None 

81 

82 return None 

83 

84 def GetGitTag(self) -> Nullable[str]: 

85 """ 

86 Returns Git tag name or ``None`` is not checked out on a tag. 

87 

88 :return: Git tag name or ``None``. 

89 :raises ServiceException: If environment variable ``GITHUB_REF`` was not found or reference doesn't start with ``refs/tags/``. 

90 """ 

91 tagPrefix = "refs/tags/" 

92 

93 try: 

94 ref = environ["GITHUB_REF"] 

95 if ref.startswith(tagPrefix): 95 ↛ 96line 95 didn't jump to line 96 because the condition on line 95 was never true

96 return ref[len(tagPrefix):] 

97 except KeyError: 

98 return None 

99 

100 return None 

101 

102 def GetGitRepository(self) -> str: 

103 """ 

104 Returns the Git repository URL. 

105 

106 :return: Git repository URL. 

107 :raises ServiceException: If environment variable ``GITHUB_REPOSITORY`` was not found. 

108 :raises ServiceException: If repository URL from ``GITHUB_REPOSITORY`` couldn't be parsed. 

109 """ 

110 try: 

111 repositoryURL = environ["GITHUB_REPOSITORY"] 

112 except KeyError as ex: 

113 raise ServiceException(f"Can't find GitHub Action environment variable 'GITHUB_REPOSITORY'.") from ex 

114 

115 try: 

116 url = URL.Parse(repositoryURL) 

117 except ToolingException as ex: 

118 raise ServiceException(f"Syntax error in repository URL '{repositoryURL}'.") from ex 

119 

120 return str(url.WithoutCredentials())