Available Plugins

Mass-driver uses a plugin system (aka the Python “entrypoints” system) for discovering and loading components from third parties.

The components are available via the following entrypoint name:

Mass-driver Component

Python entrypoint

PatchDriver

massdriver.drivers

forge

massdriver.forges

ScannerFunc

massdriver.scanners

Source

massdriver.sources

We’ve packaged separately some plugins in mass-driver-plugins, have a look there too.

These are the drivers that are packaged in by default:

Drivers

counter

Plugin name: counter

class Counter

Bases: mass_driver.drivers.bricks.SingleFileEditor

Increments a counter in a given file of repo, creating if non-existent

target_count: int = None
process_file(file_contents: str) → str | mass_driver.models.patchdriver.PatchResult

Process the counter

precommit

Plugin name: precommit

class PrecommitAutoupdate

Bases: mass_driver.models.patchdriver.PatchDriver

Run ‘pre-commit autoupdate’ in a repo

run(repo: mass_driver.models.repository.ClonedRepo) → mass_driver.models.patchdriver.PatchResult

Apply pre-commit autoupdates

shell

Plugin name: shell

class ShellDriver

Bases: mass_driver.models.patchdriver.PatchDriver

Run a generic shell command

For instance, the following is a valid “sed” invocation:

ShellDriver(command=["sed", "-i", "s/v0.1.0/v0.2.0/g", "version.txt"])

Note that the process is run inside subprocess.check_call() (raises CalledProcessError on bad exit code).

command: list[str] = None

Shell command to apply to the repository, as string list

shell: bool = True

Passed to subprocess.run, to enable true shell behaviour rather than exec

run(repo: mass_driver.models.repository.ClonedRepo) → mass_driver.models.patchdriver.PatchResult

Run the command on the repo

stamper

Plugin name: stamper

class Stamper

Bases: mass_driver.models.patchdriver.PatchDriver

Creates a new file onto a repository, aka “Stamping

Any missing folder will be created on the way.

New file’s ownership will be set after succesful write.

filepath_to_create: str = None
file_contents: str = None
file_ownership: str = '0664'

Unix file permissions for the new file

run(repo: mass_driver.models.repository.ClonedRepo) → mass_driver.models.patchdriver.PatchResult

Create the file on given repo, creating folder the way

Forges

dummy

Plugin name: dummy

class DummyForge

Bases: mass_driver.models.forge.Forge

Doesn’t do anything

PR_URL: str = None

The PR’s URL, for ease of access in tests

some_param_for_forgeconfig: pydantic.SecretStr = None

A ‘secret’ parameter to set via forgeconfig, for tests. Type enforces no-leak!

create_pr(forge_repo_url: str, base_branch: mass_driver.models.forge.BranchName, head_branch: mass_driver.models.forge.BranchName, pr_title: str, pr_body: str, draft: bool)

Send a PR, with msg body, to forge_repo for given branch of repo_path

get_pr_status(pr_url) → str

Get the PR by ID on forge_repo

property pr_statuses: list[str]

List the possible PR status returned by get_pr_status, sorted by completion

github

Plugin name: github

class GithubPersonalForge(**data)

Bases: mass_driver.forges.github.GithubBaseForge

Github API wrapper for personal user token use, capable of creating/getting PRs

Reliance on pygithub means only able to deliver personal user token PRs, no Github app authentication.

Initialization

Log in to Github first

token: pydantic.SecretStr = None

Github personal access token

github-app

Plugin name: github-app

class GithubAppForge(**data)

Bases: mass_driver.forges.github.GithubBaseForge

Create PRs on Github as a Github App, not user

Initialization

Log in to Github first

app_id: pydantic.SecretStr = None
app_private_key: pydantic.SecretStr = None
app_installation_id: int = None

Sources

csv-filelist

Plugin name: csv-filelist

class CSVFileSource

Bases: mass_driver.models.repository.Source

Source reading repos from CSV file, attaching to patch_data any extra fields

csv_file: pydantic.FilePath = None

The path to the CSV file that holds repos

reader_args: dict = None

Keyword-arguments to pass to csv.DictReader

discover() → mass_driver.models.repository.IndexedRepos

Discover a list of repositories

repo-filelist

Plugin name: repo-filelist

class RepoFilelistSource

Bases: mass_driver.models.repository.Source

A Source reads repo list from file

repo_file: pydantic.FilePath = None

The path to the file that holds repos to read

discover() → mass_driver.models.repository.IndexedRepos

Discover a list of repositories

repo-list

Plugin name: repo-list

class RepolistSource

Bases: mass_driver.models.repository.Source

A Source that just returns a pre-configured list of repositories

repos: list[mass_driver.models.repository.RepoUrl] = None

The configured list of repositories to use, as list of cloneable URL

discover() → mass_driver.models.repository.IndexedRepos

Discover a list of repositories

template-filelist

Plugin name: template-filelist

class TemplateFileSource

Bases: mass_driver.models.repository.Source

A Source that reads repo id from file, templating the clone URL around it

repo_file: pydantic.FilePath = None

The path to the newline-delimited file that holds repo ids

clone_url_template: str = None

The repo clone URL template string, ready to inject ID into. Must contain {id}

discover() → mass_driver.models.repository.IndexedRepos

Discover a list of repositories

Scanners

dockerfile-from

Plugin name: dockerfile-from

mass_driver.scanners.basic_scanners.dockerfile_from_scanner(repo: pathlib.Path) → dict[str, Any][source]

Report the repo’s Dockerfile’s FROM line(s)

root-files

Plugin name: root-files

mass_driver.scanners.basic_scanners.rootlevel_files(repo: pathlib.Path) → dict[str, Any][source]

Detect some files at the root of the repo