Package: phylum
phylum-ciUtilities for integrating Phylum into CI pipelines (and beyond)Installation and usageInstallationThephylumPython package is pip installable for the environment of your choice:pipinstallphylumIt can also be installed in an isolated environment with the excellentpipxtool:# Globally install the app(s) on your system in an isolated virtual environment for the packagepipxinstallphylum# Use the apps from the package in an ephemeral environmentpipxrun--specphylumphylum-init<options>
pipxrun--specphylumphylum-ci<options>These installation methods require Python 3.9+ to run.
For a self contained environment, consider using the Docker image as described below.UsageThephylumPython package exposes its functionality with a command line interface (CLI).
To view the options available from the CLI, print the help message from one of the scripts provided as entry points:phylum-init-h
phylum-ci-hThe functionality can also be accessed by calling the module:python-mphylum.init-h
python-mphylum.ci-hThe functionality is also exposed in the form of a Docker image:# Get the `latest` tagged imagedockerpullphylumio/phylum-ci# View the helpdockerrun--rmphylumio/phylum-ciphylum-ci--help# Export a Phylum token (e.g., from `phylum auth token`)exportPHYLUM_API_KEY=$(phylumauthtoken)# Run it from a git repo directory containing at least one supported lockfile or manifestdockerrun-it--rm-ePHYLUM_API_KEY--mounttype=bind,src=$(pwd),dst=/phylum-w/phylumphylumio/phylum-ciThe default Docker image containsgitand the installedphylumPython package.
It also contains an installed version of the Phylum CLI and all required tools needed forlockfile generation.
An advantage of using the default Docker image is that the complete environment is packaged and made available with
components that are known to work together.One disadvantage to the default image is it's size. It can take a while to download and may provide more tools than
required for your specific use case. Specialslimtags of thephylum-ciimage are provided as an alternative.
These tags differ from the default image in that they do not contain the required tools needed forlockfile generation(with the exception of thepiptool). Theslimtags are significantly smaller and will allow integrations relying
on them to complete faster. They are useful for those instances wherenomanifest files are present and/oronlylockfiles are used.# Get the "latest" `slim` tagged imagedockerpullphylumio/phylum-ci:slimWhen using thelatesttagged image, the version of the Phylum CLI is thelatestavailable.
There are additional image tag options available to specify a specific release of thephylum-ciproject and a specific
version of the Phylum CLI, in the form of<phylum-ci version>-CLIv<Phylum CLI version>.
Each of these also has a-slimvariant that does not supportlockfile generation. Here are image tag examples:# Get the most current release of *both* `phylum-ci` and the Phylum CLIdockerpullphylumio/phylum-ci:latest# Get the image with `phylum-ci` version 0.35.2 and Phylum CLI version 5.7.1dockerpullphylumio/phylum-ci:0.35.2-CLIv5.7.1# Get the `slim` image with `phylum-ci` version 0.36.0 and Phylum CLI version 5.7.1dockerpullphylumio/phylum-ci:0.36.0-CLIv5.7.1-slimphylum-initScript Entry PointThephylum-initscript can be used to fetch and install the Phylum CLI.
It will attempt to install the latest released version of the CLI but can be specified to fetch a specific version.
It will attempt to automatically determine the correct CLI release, based on the platform where the script is run, but
a specific release target can be specified.
It will accept a Phylum token from an environment variable or specified as an option, but will also function in the case
that no token is provided. This can be because there is already a token set that should continue to be used or because
no token exists and one will need to be manually created or set, after the CLI is installed.The options forphylum-init, automatically updated to be current for the latest release:HINT:Click on the image to bring up the SVG file, which should allow for search and copy/paste functionality.phylum-ciScript Entry PointThephylum-ciscript is for analyzing dependency file (lockfiles and manifests) changes.
The script can be used locally or from within a Continuous Integration (CI) environment.
It will attempt to detect the CI platform based on the environment from which it is run and act accordingly.
The current CI platforms/environments supported are:Platform/EnvironmentInformation LinkGitHub ActionsDocumentationGitLab CIDocumentationAzure PipelinesDocumentationBitbucket PipelinesDocumentationGitpre-commitHooksDocumentationThere is also support for local use. This is the "fall-through" case used when no other environment is detected.
This can be useful to analyze dependency files locally, prior to or after submitting a pull/merge request (PR/MR) to a
CI system. It can also help in establishing a successful submission prior to submitting a PR/MR to a CI system.
Additionally, local use can aid troubleshooting after submitting a PR/MR to a CI system and getting unexpected results.The options forphylum-ci, automatically updated to be current for the latest release:HINT:Click on the image to bring up the SVG file, which should allow for search and copy/paste functionality.LicenseCopyright (C) 2022  Phylum, Inc.This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation, either version 3 of the License or any later version.This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with this program.
If not, seehttps://www.gnu.org/licenses/gpl.htmlor write tophylum@phylum.ioorengineering@phylum.ioContributingSuggestions and help are welcome. Feel free to open an issue or otherwise contribute.
More information is available on thecontributing documentationpage.Code of ConductEveryone participating in thephylum-ciproject, and in particular in the issue tracker and pull requests, is
expected to treat other people with respect and more generally to follow the guidelines articulated in theCode of Conduct.Security DisclosuresFound a security issue in this repository? See thesecurity policyfor details on coordinated disclosure.Change logAll notable changes to this project are documented in theCHANGELOG.The format of the change log is based onKeep a Changelog,
and this project adheres toSemantic Versioning.
The entries in the changelog are primarily automatically generated through the use ofconventional commitsand thePython Semantic Releasetool.
However, some entries may be manually edited, where it helps for clarity and understanding.