Skip to content

git_env

GitEnv

Bases: BaseModel

Object to store the git configuration.

Attributes:

Name Type Description
sha str

...
branch str

...
target_branch str

...
commit Commit | None

...
pull_request PullRequest | None

...
release Release | None

...
Source code in m/ci/git_env.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
class GitEnv(BaseModel):
    """Object to store the git configuration."""

    sha: str
    branch: str
    target_branch: str
    commit: Commit | None = None
    pull_request: PullRequest | None = None
    release: Release | None = None

    def get_pr_branch(self) -> str:
        """Get the pull request branch or empty string.

        Returns:
            The name of the pull request branch or an empty string when not
            dealing with a pull request.
        """
        return self.pull_request.pr_branch if self.pull_request else ''

    def get_pr_number(self) -> int:
        """Get the pull request number or 0 if not a pull request.

        Returns:
            The pull request number or 0 if not a pull request.
        """
        return self.pull_request.pr_number if self.pull_request else 0

    def is_release(self, config: Config) -> bool:
        """Determine if the current commit should create a release.

        Args:
            config: The `m` configuration.

        Returns:
            True if we are dealing with a release.
        """
        if not self.commit:
            return False
        release_prefix = get_release_prefix(config)
        hotfix_prefix = get_hotfix_prefix(config)
        if config.uses_m_flow() and self.branch != config.m_flow.master_branch:
            return False
        if config.uses_git_flow():
            if self.branch != config.git_flow.master_branch:
                return False
        return (
            self.commit.is_release(release_prefix)
            or self.commit.is_release(hotfix_prefix)
        )

    def is_release_pr(self, config: Config) -> bool:
        """Determine if the the current pr is a release pr.

        Args:
            config: The `m` configuration.

        Returns:
            True if we are dealing with a release pr.
        """
        if not self.pull_request:
            return False
        release_prefix = get_release_prefix(config)
        return self.pull_request.is_release_pr(release_prefix)

    def is_hotfix_pr(self, config: Config) -> bool:
        """Determine if the the current pr is a hotfix pr.

        It is a release pr as far as the pull request should see it but
        from the context of the git environment we need to label it as a
        hotfix pr.

        Args:
            config: The m configuration object.

        Returns:
            True if the we are dealing with hotfix pr.
        """
        if not self.pull_request:
            return False
        hotfix_prefix = get_hotfix_prefix(config)
        return self.pull_request.is_release_pr(hotfix_prefix)

    def get_build_tag(self, config: Config, run_id: str) -> Res[str]:
        """Create a build tag for the current commit.

        It is tempting to use the config_version when creating a build tag for
        pull requests or branches. This will only be annoying when testing.

        Consider the following scenario. An application is being tested with
        `1.0.1-pr99.b123`. When using docker you may want to refer to the
        latest pr build by using `1.0.1-pr99`. Now lets say that a release
        happened and now the config_version is at `1.1.0`. The application
        build will not get the latest changes because the new changes are in
        `1.1.0-pr99`.

        There are two solutions, either always state the version that is
        being used or make a tag to depend only on the pull request number.
        This is the reason why for prs (constantly changing) we avoid
        using the version in the configuration.

        For release prs we use `rc` followed by the pull request. In this case
        it is safe to use config_version given that there should only be
        one release at a time. We treat hotfixes similar to releases.

        Git flow will generate a special build tag: SKIP. This will happen when
        we try to merge a release or hotfix branch to the develop branch.

        Args:
            config: The `m` configuration.
            run_id: A unique identifier for the run/job.

        Returns:
            A unique identifier for the build. This tag is compatible with
            both `npm` and `docker`.
        """
        ver_input = _version_inputs(self, config, run_id)
        if ver_input:
            return Good(build_m_tag(ver_input, config))
        return Good('SKIP')

    def get_py_tag(self, config: Config, run_id: str) -> Res[str]:
        """Create a python tag for the current commit.

        Args:
            config: The `m` configuration.
            run_id: A unique identifier for the run/job.

        Returns:
            A unique identifier for the build. This tag is compatible with
            python.
        """
        ver_input = _version_inputs(self, config, run_id)
        if ver_input:
            return Good(build_py_tag(ver_input, config))
        return Good('SKIP')

get_build_tag(config, run_id)

Create a build tag for the current commit.

It is tempting to use the config_version when creating a build tag for pull requests or branches. This will only be annoying when testing.

Consider the following scenario. An application is being tested with 1.0.1-pr99.b123. When using docker you may want to refer to the latest pr build by using 1.0.1-pr99. Now lets say that a release happened and now the config_version is at 1.1.0. The application build will not get the latest changes because the new changes are in 1.1.0-pr99.

There are two solutions, either always state the version that is being used or make a tag to depend only on the pull request number. This is the reason why for prs (constantly changing) we avoid using the version in the configuration.

For release prs we use rc followed by the pull request. In this case it is safe to use config_version given that there should only be one release at a time. We treat hotfixes similar to releases.

Git flow will generate a special build tag: SKIP. This will happen when we try to merge a release or hotfix branch to the develop branch.

Parameters:

Name Type Description Default
config Config

The m configuration.

 required
run_id str

A unique identifier for the run/job.

 required

Returns:

Type Description
Res[str]

A unique identifier for the build. This tag is compatible with
Res[str]

both npm and docker.
Source code in m/ci/git_env.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def get_build_tag(self, config: Config, run_id: str) -> Res[str]:
    """Create a build tag for the current commit.

    It is tempting to use the config_version when creating a build tag for
    pull requests or branches. This will only be annoying when testing.

    Consider the following scenario. An application is being tested with
    `1.0.1-pr99.b123`. When using docker you may want to refer to the
    latest pr build by using `1.0.1-pr99`. Now lets say that a release
    happened and now the config_version is at `1.1.0`. The application
    build will not get the latest changes because the new changes are in
    `1.1.0-pr99`.

    There are two solutions, either always state the version that is
    being used or make a tag to depend only on the pull request number.
    This is the reason why for prs (constantly changing) we avoid
    using the version in the configuration.

    For release prs we use `rc` followed by the pull request. In this case
    it is safe to use config_version given that there should only be
    one release at a time. We treat hotfixes similar to releases.

    Git flow will generate a special build tag: SKIP. This will happen when
    we try to merge a release or hotfix branch to the develop branch.

    Args:
        config: The `m` configuration.
        run_id: A unique identifier for the run/job.

    Returns:
        A unique identifier for the build. This tag is compatible with
        both `npm` and `docker`.
    """
    ver_input = _version_inputs(self, config, run_id)
    if ver_input:
        return Good(build_m_tag(ver_input, config))
    return Good('SKIP')

get_pr_branch()

Get the pull request branch or empty string.

Returns:

Type Description
str

The name of the pull request branch or an empty string when not
str

dealing with a pull request.
Source code in m/ci/git_env.py 
90
91
92
93
94
95
96
97
def get_pr_branch(self) -> str:
    """Get the pull request branch or empty string.

    Returns:
        The name of the pull request branch or an empty string when not
        dealing with a pull request.
    """
    return self.pull_request.pr_branch if self.pull_request else ''

get_pr_number()

Get the pull request number or 0 if not a pull request.

Returns:

Type Description
int

The pull request number or 0 if not a pull request.
Source code in m/ci/git_env.py 
 99
100
101
102
103
104
105
def get_pr_number(self) -> int:
    """Get the pull request number or 0 if not a pull request.

    Returns:
        The pull request number or 0 if not a pull request.
    """
    return self.pull_request.pr_number if self.pull_request else 0

get_py_tag(config, run_id)

Create a python tag for the current commit.

Parameters:

Name Type Description Default
config Config

The m configuration.

 required
run_id str

A unique identifier for the run/job.

 required

Returns:

Type Description
Res[str]

A unique identifier for the build. This tag is compatible with
Res[str]

python.
Source code in m/ci/git_env.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def get_py_tag(self, config: Config, run_id: str) -> Res[str]:
    """Create a python tag for the current commit.

    Args:
        config: The `m` configuration.
        run_id: A unique identifier for the run/job.

    Returns:
        A unique identifier for the build. This tag is compatible with
        python.
    """
    ver_input = _version_inputs(self, config, run_id)
    if ver_input:
        return Good(build_py_tag(ver_input, config))
    return Good('SKIP')

is_hotfix_pr(config)

Determine if the the current pr is a hotfix pr.

It is a release pr as far as the pull request should see it but from the context of the git environment we need to label it as a hotfix pr.

Parameters:

Name Type Description Default
config Config

The m configuration object.

 required

Returns:

Type Description
bool

True if the we are dealing with hotfix pr.
Source code in m/ci/git_env.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def is_hotfix_pr(self, config: Config) -> bool:
    """Determine if the the current pr is a hotfix pr.

    It is a release pr as far as the pull request should see it but
    from the context of the git environment we need to label it as a
    hotfix pr.

    Args:
        config: The m configuration object.

    Returns:
        True if the we are dealing with hotfix pr.
    """
    if not self.pull_request:
        return False
    hotfix_prefix = get_hotfix_prefix(config)
    return self.pull_request.is_release_pr(hotfix_prefix)

is_release(config)

Determine if the current commit should create a release.

Parameters:

Name Type Description Default
config Config

The m configuration.

 required

Returns:

Type Description
bool

True if we are dealing with a release.
Source code in m/ci/git_env.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def is_release(self, config: Config) -> bool:
    """Determine if the current commit should create a release.

    Args:
        config: The `m` configuration.

    Returns:
        True if we are dealing with a release.
    """
    if not self.commit:
        return False
    release_prefix = get_release_prefix(config)
    hotfix_prefix = get_hotfix_prefix(config)
    if config.uses_m_flow() and self.branch != config.m_flow.master_branch:
        return False
    if config.uses_git_flow():
        if self.branch != config.git_flow.master_branch:
            return False
    return (
        self.commit.is_release(release_prefix)
        or self.commit.is_release(hotfix_prefix)
    )

is_release_pr(config)

Determine if the the current pr is a release pr.

Parameters:

Name Type Description Default
config Config

The m configuration.

 required

Returns:

Type Description
bool

True if we are dealing with a release pr.
Source code in m/ci/git_env.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
def is_release_pr(self, config: Config) -> bool:
    """Determine if the the current pr is a release pr.

    Args:
        config: The `m` configuration.

    Returns:
        True if we are dealing with a release pr.
    """
    if not self.pull_request:
        return False
    release_prefix = get_release_prefix(config)
    return self.pull_request.is_release_pr(release_prefix)

get_git_env(config, env_vars)

Obtain the git environment by asking Github's API.

Parameters:

Name Type Description Default
config Config

The m configuration object.

 required
env_vars EnvVars

The environment variables.

 required

Returns:

Type Description
Res[GitEnv]

The git environment object or an issue.
Source code in m/ci/git_env.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
def get_git_env(config: Config, env_vars: EnvVars) -> Res[GitEnv]:
    """Obtain the git environment by asking Github's API.

    Args:
        config: The m configuration object.
        env_vars: The environment variables.

    Returns:
        The git environment object or an issue.
    """
    branch = _remove_strings(env_vars.git_branch, ['refs/heads/', 'heads/'])
    sha = env_vars.git_sha
    git_env = GitEnv(sha=sha, branch=branch, target_branch=branch)

    # quick exit for local environment
    if not env_vars.ci_env:
        return Good(git_env)

    pr_number = get_pr_number(branch)
    git_env_box = get_ci_run_info(
        token=env_vars.github_token,
        commit_info=CommitInfo(
            owner=config.owner,
            repo=config.repo,
            sha=env_vars.git_sha,
        ),
        pr_number=pr_number,
        file_count=100,
        include_release=True,
    )
    if isinstance(git_env_box, Bad):
        return issue('git_env failure', cause=git_env_box.value)

    res = git_env_box.value
    pr = res.pull_request

    if pr and config.require_pr_changelog and not pr.changelog_updated():
        can_bypass: bool = bool(config.changelog_bypassers) and pr.author.login in config.changelog_bypassers

        # If this is a huge PR we'll bypass it, the file may not be present in
        # the list of files.
        if not can_bypass and pr.file_count < 100:
            return issue('missing CHANGELOG.md in PR', context={'pr': pr.model_dump()})

    git_env.sha = res.commit.sha
    git_env.target_branch = pr.target_branch if pr else branch
    git_env.commit = res.commit
    git_env.pull_request = res.pull_request
    git_env.release = res.release
    return Good(git_env)

get_hotfix_prefix(config)

Find out the hotfix prefix.

Parameters:

Name Type Description Default
config Config

The m configuration. Its workflow is used to determine the prefix.

 required

Returns:

Type Description
str | None

The hofix prefix or None if not using a supported workflow.
Source code in m/ci/git_env.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def get_hotfix_prefix(config: Config) -> str | None:
    """Find out the hotfix prefix.

    Args:
        config:
            The m configuration. Its workflow is used to determine the prefix.

    Returns:
        The hofix prefix or None if not using a supported workflow.
    """
    if config.uses_git_flow():
        return config.git_flow.hotfix_prefix
    if config.uses_m_flow():
        return config.m_flow.hotfix_prefix
    return None

get_pr_number(branch)

Retrieve the pull request number from the branch name.

Parameters:

Name Type Description Default
branch str

The branch name from where the pr number is extracted.py

 required

Returns:

Type Description
int | None

The pr number if the branch is a pull request otherwise None.
Source code in m/ci/git_env.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
def get_pr_number(branch: str) -> int | None:
    """Retrieve the pull request number from the branch name.

    Args:
        branch: The branch name from where the pr number is extracted.py

    Returns:
        The pr number if the branch is a pull request otherwise `None`.
    """
    if 'pull/' in branch:
        parts = branch.split('/')
        return int(parts[parts.index('pull') + 1])
    return None

get_release_prefix(config)

Find out the release prefix.

Parameters:

Name Type Description Default
config Config

The m configuration. Its workflow is used to determine the prefix.

 required

Returns:

Type Description
str | None

The release prefix or None if not using a supported workflow.
Source code in m/ci/git_env.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def get_release_prefix(config: Config) -> str | None:
    """Find out the release prefix.

    Args:
        config:
            The m configuration. Its workflow is used to determine the prefix.

    Returns:
        The release prefix or None if not using a supported workflow.
    """
    if config.uses_git_flow():
        return config.git_flow.release_prefix
    if config.uses_m_flow():
        return config.m_flow.release_prefix
    return None