git Configuration¶

The Mayhem API testing CLI tool, mapi, leverages git if ran within a git repository. It detects the author, branch, commit SHA, commit message, and the parent commit SHA. This information is attached to a job and helps Mayhem display useful information about a job.

Default Branch¶

The default branch is considered the baseline for comparisons and overall target health. Typical default branches are main, master or develop. The default branch is set on the target's settings page.

Jobs ran on the default branch will have a default tag shown on the job's row.

Issues found on the default branch will be replayed on other branches.

Diffs¶

Mayhem supports two different scenarios for computing the difference between jobs with git context.

Note: To auto-detect diffs, Mayhem needs a non-shallow history.

Default Branch Job¶

Each default branch job is compared to the last job of the previous commit.

If the previous commit of the default branch does not have a job, because of a pipeline failure or CI configuration, a reason explaining the cause of the missing diff will be shown in place of a number.

For example, a git command to find the previous commit SHA is git rev-parse HEAD~1.

Jenkins¶

Jenkins can group commits together. Default branch jobs on Jenkins will use the value of the environment variable GIT_PREVIOUS_SUCCESSFUL_COMMIT if it is available. Jenkins publishes the available environment variables at your-jenkins.host/env-vars.html. If GIT_PREVIOUS_SUCCESSFUL_COMMIT is not available, Mayhem will fall back to the logic above.

Branch Job¶

A job ran on any branch other than the default branch is compared to the last job of the commits merge base with the default branch.

If a merge base commit cannot be found, or a job does not exist for it because of a pipeline failure or CI configuration, a reason explaining the cause of the missing diff will be shown in place of a number.

The example of a git command is git merge-base HEAD origin/main.

Git History¶

Some CI providers like GitHub Actions fetch a shallow clone of the repository by default. We recommend cloning a full repository if possible. If it is not desirable or possible to clone the full repository, a partial clone of a depth that will capture the merge base is recommended.

If Mayhem cannot detect the parent SHA with the context it is given, it will try to deepen the repository by 50 commits and retry the SHA detection a single time. This requires that fetch access to the remote repository is available to git in the CI step.

Identifying the Previous Job¶

The previous job that was used as a baseline for a diff can be seen by hovering over the diff stats on the job row.

Overriding the Parent SHA¶

If a project's git workflow is not compatible with the default behaviour, override the parent SHA by supplying it:

mapi run \
     <target_name> \
     auto \
     <path_to_api_specification> \
     --url "https://example.com" \
     --parent-sha <your_sha>

Troubleshooting¶

No git branch or commit information¶

To enable git support for mapi, ensure that it is: * Ran within the path of a git repository * git is available on the Path

No diffs¶

Try adding the shell scripts to your CI provider before executing mapi and verify that the output is a SHA:

# this should return the SHA when the default branch is checked out
git rev-parse HEAD~1

# this should return a SHA when 
git merge-base HEAD origin/main