Bitbucket Pipelines Integration
Bitbucket Pipelines Integration
Add the following "Phylum Analyze" step to a
bitbucket-pipelines.yml configuration, in one or more pipeline start
# Ensure these variables are set at the repository or workspace level: # - `PHYLUM_API_KEY`: Phylum authentication token # - `BITBUCKET_TOKEN`: repository, project, or workspace access token with `pullrequest` scope - step: name: Phylum Analyze image: phylumio/phylum-ci:latest clone: depth: full script: - phylum-ci
Once configured for a repository, the Bitbucket Pipelines integration will provide analysis of project
dependencies from a lockfile. This can happen in a branch or default pipeline as a result of a commit or in a pull
request (PR) pipeline. For PR pipelines, analyzed dependencies will include any that are added/modified in the PR.
For branch pipelines, the analyzed dependencies will be determined by comparing the lockfile in the branch to the
default branch. All dependencies will be analyzed when the branch pipeline is run on the default branch.
The results will be provided in the pipeline logs and provided as a comment on the PR. The CI job will return an
error (i.e., fail the build) if any of the analyzed dependencies fail to meet the project risk thresholds for any
of the five Phylum risk domains:
- Vulnerability (aka
- Malicious Code (aka
- Engineering (aka
- License (aka
- Author (aka
See Phylum Risk Domains documentation for more detail.
NOTE: It is not enough to have the total project threshold set. Individual risk domain threshold values must be
set, either in the UI or with
phylum-ci options, in order to enable analysis results for CI. Otherwise, the risk
domain is considered disabled and the threshold value used will be zero (0).
There will be no comment if no dependencies were added or modified for a given PR.
If one or more dependencies are still processing (no results available), then the comment will make that clear and
the CI job will only fail if dependencies that have completed analysis results do not meet the specified project
Bitbucket Cloud is supported for repositories hosted on https://bitbucket.org/. Bitbucket Data Center is not
The Bitbucket Pipelines environment is primarily supported through the use of a Docker image. The pre-requisites for
using this image are:
- Access to the phylumio/phylum-ci Docker image
- A Bitbucket access token with API access
- This is only required when using the integration in pull request pipelines
- The token needs the
- A Phylum token with API access
- Contact Phylum or register to gain access
- See also
phylum auth registercommand documentation
- See also
- Consider using a bot or group account for this token
- Contact Phylum or register to gain access
- Access to the Phylum API endpoints
- That usually means a connection to the internet, optionally via a proxy
.phylum_projectfile exists at the root of the repository
phylum initcommand documentation
Phylum analysis of dependencies can be added to existing CI workflows or on it's own with this minimal configuration:
# Ensure these variables are set at the repository or workspace level: # - `PHYLUM_API_KEY`: Phylum authentication token # - `BITBUCKET_TOKEN`: repository, project, or workspace access token with `pullrequest` scope pipelines: pull-requests: '**': - step: name: Phylum Analyze PR image: phylumio/phylum-ci:latest clone: depth: full script: - phylum-ci default: - step: name: Phylum Analyze branch image: phylumio/phylum-ci:latest clone: depth: full script: - phylum-ci
This configuration contains pipeline definitions for the
default start conditions. It will
run for all pull requests and pushes to any branch. It does not override any of the
phylum-ci arguments, which
are all either optional or default to secure values. Let's take a deeper dive into each part of the configuration:
There are several user-defined variables needed to ensure the
phylum-ci tool is able to perform it's job. Ensure
these variables are set at the repository or workspace level. See the user-defined variables documentation
for more info.
A Phylum token with API access is required to perform analysis on project dependencies.
Contact Phylum or register to gain access.
phylum auth register command documentation and consider using a bot or group account
for this token. Provide the token value in a user-defined variable named
A Bitbucket token with API access is required to use the API (e.g., to post comments). This can be a repository,
project, or workspace access token. The token needs the
pullrequest scope. The name given to the token will be
the one that appears to post the comments on the PR. Therefore, it might be worth naming it something like
Phylum Analysis. See the Bitbucket Access Tokens documentation for more info.
Note, the Bitbucket token is only required when this Phylum integration is used in
pull request pipelines. It is not required when used in branch based pipelines. Provide the token
value in a user-defined variable named
Values for the
PHYLUM_API_KEY variables are sensitive and should be set as a
secured variable. Care should be taken to protect them appropriately.
Pipeline start conditions
There are a handful of different pipeline start conditions available to trigger CI. The Phylum
analysis step can be included in most of these, or even multiple start conditions. The exceptions may be
custom pipelines. The example configuration adds the step to both the
pipelines: # Pipeline definition for pull requests pull-requests: '**': # Glob pattern to specify all branches - step: # Add the Phylum Analyze step here # Pipeline definition for all branches that don't # match a pipeline definition in other sections default: - step: # Add the Phylum Analyze step here
The step name is optional, can be named what you like, and have different names depending on the pipeline context.
name step option documentation for more information.
pipelines: pull-requests: '**': - step: name: Phylum Analyze PR # Name this what you like default: - step: name: Phylum Analyze branch # Name this what you like
Docker image selection
Choose the Docker image tag to match your comfort level with image dependencies.
latest is a "rolling" tag that
will point to the image created for the latest released
phylum-ci Python package. A particular version tag
0.23.1-CLIv4.4.0) is created for each release of the
phylum-ci Python package and should not change
However, to be certain that the image does not change...or be warned when it does because it won't be available
anymore...use the SHA256 digest of the tag. The digest can be found by looking at the
tags on Docker Hub or with the command:
# NOTE: The command-line JSON processor `jq` is used here for the sake of a one line example. It is not required. ❯ docker manifest inspect --verbose phylumio/phylum-ci:0.23.1-CLIv4.4.0 | jq .Descriptor.digest "sha256:f2840ad448278e26b69a076a93f2c90cb083803243a614f5efb518f032626578"
For instance, at the time of this writing, all of these tag references pointed to the same image:
# NOTE: These are examples. Only one image line for `phylum-ci` is expected. # Not specifying a tag means a default of `latest` image: phylumio/phylum-ci # Be more explicit about wanting the `latest` tag image: phylumio/phylum-ci:latest # Use a specific release version of the `phylum-ci` package image: phylumio/phylum-ci:0.23.1-CLIv4.4.0 # Use a specific image with it's SHA256 digest image: phylumio/[email protected]:f2840ad448278e26b69a076a93f2c90cb083803243a614f5efb518f032626578
Only the last tag reference, by SHA256 digest, is guaranteed to not have the underlying image it points to change.
See the Docker image option and build environment documentation for more information.
Git clone behavior
git version control system is used within the
phylum-ci package to do things like determine if there was a
lockfile change and, when specified, report on new dependencies only. Therefore, a full clone of the repository is
required to ensure that the local working copy is always pristine and history is available to pull the requested
- step: clone: depth: full
See the git clone behavior documentation for more information.
The script arguments to the Docker image are the way to exert control over the execution of the Phylum analysis.
phylum-ci script entry point is expected to be called. It has a number of arguments that are all optional
and defaulted to secure values. To view the arguments, their description, and default values,
run the script with
--help output as specified in the Usage section of the top-level README.md or
view the script options output for the latest release.
# NOTE: These are examples. Only one script entry line for `phylum-ci` is expected. script: # Use the defaults for all the arguments. # The default behavior is to only analyze newly added dependencies against # the risk domain threshold levels set at the Phylum project level. - phylum-ci # Consider all dependencies in analysis results instead of just the newly added ones. # The default is to only analyze newly added dependencies, which can be useful for # existing code bases that may not meet established project risk thresholds yet, # but don't want to make things worse. Specifying `--all-deps` can be useful for # casting the widest net for strict adherence to Quality Assurance (QA) standards. - phylum-ci --all-deps # Some lockfile types (e.g., Python/pip `requirements.txt`) are ambiguous in that # they can be named differently and may or may not contain strict dependencies. # In these cases, it is best to specify an explicit lockfile path. - phylum-ci --lockfile requirements-prod.txt # Thresholds for the five risk domains may be set at the Phylum project level. # They can be set differently for CI environments to "fail the build." - | phylum-ci \ --vul-threshold 60 \ --mal-threshold 60 \ --eng-threshold 70 \ --lic-threshold 90 \ --aut-threshold 80 # Ensure the latest Phylum CLI is installed. - phylum-ci --force-install # Install a specific version of the Phylum CLI. - phylum-ci --phylum-release 4.6.0 --force-install # Mix and match for your specific use case. - | phylum-ci \ --vul-threshold 60 \ --mal-threshold 60 \ --eng-threshold 70 \ --lic-threshold 90 \ --aut-threshold 80 \ --lockfile requirements-prod.txt \ --all-deps
It is also possible to make direct use of the
phylum Python package within CI.
This may be necessary if the Docker image is unavailable or undesirable for some reason.
To use the
phylum package, install it and call the desired entry points from a script under your control.
See the Installation and Usage sections of the README file for more detail.
Updated about 1 month ago