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 """ 

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

46 """ 

47 

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

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

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

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

52 

53 def GetPlatform(self) -> Platform: 

54 return Platform("github") 

55 

56 def GetGitHash(self) -> str: 

57 """ 

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

59 

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

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

62 """ 

63 try: 

64 return environ["GITHUB_SHA"] 

65 except KeyError as ex: 

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

67 

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

69 """ 

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

71 

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

73 :raises ServiceException: If environment variable ``GITHUB_REF`` was not found or reference doesn't start with 

74 ``refs/heads/``. 

75 """ 

76 branchPrefix = "refs/heads/" 

77 

78 try: 

79 ref = environ["GITHUB_REF"] 

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

81 return ref[len(branchPrefix):] 

82 except KeyError: 

83 return None 

84 

85 return None 

86 

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

88 """ 

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

90 

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

92 :raises ServiceException: If environment variable ``GITHUB_REF`` was not found or reference doesn't start with 

93 ``refs/tags/``. 

94 """ 

95 tagPrefix = "refs/tags/" 

96 

97 try: 

98 ref = environ["GITHUB_REF"] 

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

100 return ref[len(tagPrefix):] 

101 except KeyError: 

102 return None 

103 

104 return None 

105 

106 def GetGitRepository(self) -> str: 

107 """ 

108 Returns the Git repository URL. 

109 

110 :return: Git repository URL. 

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

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

113 """ 

114 try: 

115 repositoryURL = environ["GITHUB_REPOSITORY"] 

116 except KeyError as ex: 

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

118 

119 try: 

120 url = URL.Parse(repositoryURL) 

121 except ToolingException as ex: 

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

123 

124 return str(url.WithoutCredentials())