From 5b988b9c408b2b1088f5fde3f53386b36540798c Mon Sep 17 00:00:00 2001 From: Charles Coggins Date: Wed, 13 Jul 2022 10:55:52 -0500 Subject: [PATCH 1/2] docs: add integration documentation to Phylum docs page The docs have been updated to contain the new readme.com category for "Integrations". They have also been revised to ensure the links will work correctly from either/both GitHub and the Phylum docs portal. Finally, an overview page was created to point to all the other pages. Closes #75 --- docs/github_actions.md | 51 ++++++++++++++++++++++------------- docs/gitlab_ci.md | 47 +++++++++++++++++++++----------- docs/integrations_overview.md | 33 +++++++++++++++++++++++ 3 files changed, 97 insertions(+), 34 deletions(-) create mode 100644 docs/integrations_overview.md diff --git a/docs/github_actions.md b/docs/github_actions.md index c6135ac5..d02dd7a1 100644 --- a/docs/github_actions.md +++ b/docs/github_actions.md @@ -1,32 +1,47 @@ +--- +title: GitHub Actions Integration +category: 62cdf6722c2c1602a4b69643 +hidden: false +--- # GitHub Actions Integration ## Overview -Integrations with the GitHub Actions environment are available in several forms. The primary method is through the -`phylum-dev/phylum-analyze-pr-action` action. This action is available for direct use now and full documentation can be -found by viewing the [Phylum Analyze PR action repository](https://github.com/phylum-dev/phylum-analyze-pr-action). +Integrations with the GitHub Actions environment are available in several forms. +The primary method is through the `phylum-dev/phylum-analyze-pr-action` action. +This action is available in the [GitHub Actions Marketplace][marketplace]. +Full documentation can be found there or by viewing the [Phylum Analyze PR action repository][repo] directly. -The action will be available for discovery in the [GitHub Actions Marketplace](https://github.com/marketplace) soon. +The Phylum Analyze PR action is a [Docker container action][container_action]. +This has the advantage of ensuring everything needed to work with Phylum for analyzing a PR +for dependencies in a lockfile is self contained and known to function as a single unit. +There are some disadvantages and some users may prefer a different solution. -The Phylum Analyze PR action is a [Docker container action][container]. This has the advantage of ensuring everything -needed to work with Phylum for analyzing a PR for dependencies in a lockfile is self contained and known to function as -a single unit. There are some disadvantages and some users may prefer a different solution. - -[container]: https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action +[marketplace]: https://github.com/marketplace/actions/phylum-analyze-pr +[repo]: https://github.com/phylum-dev/phylum-analyze-pr-action +[container_action]: https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action ## Alternatives ### Direct `phylum` Python Package Use -It is also possible to make direct use of the [`phylum` Python package](https://pypi.org/project/phylum/) 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](../README.md#installation) and [Usage](../README.md#usage) sections of the [README file](../README.md) -for more detail. +It is also possible to make direct use of the [`phylum` Python package][pypi] 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][installation] and [Usage][usage] sections of the [README file][readme] for more detail. + +[pypi]: https://pypi.org/project/phylum/ +[readme]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md +[installation]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md#installation +[usage]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md#usage ### Container Jobs -There is another way to use the `phylumio/phylum-ci` Docker image, but without it being encapsulated in the Phylum -Analyze PR action directly. GitHub Actions allows for workflows to run a job within a container, using the `container:` -statement in the workflow file. These are known as container jobs. More information can be found in GitHub -documentation: ["Running jobs in a container"](https://docs.github.com/actions/using-jobs/running-jobs-in-a-container). +There is another way to use the `phylumio/phylum-ci` Docker image, +but without it being encapsulated in the Phylum Analyze PR action directly. +GitHub Actions allows for workflows to run a job within a container, +using the `container:` statement in the workflow file. +These are known as container jobs. +More information can be found in GitHub documentation: ["Running jobs in a container"][container_job]. + +[container_job]: https://docs.github.com/actions/using-jobs/running-jobs-in-a-container diff --git a/docs/gitlab_ci.md b/docs/gitlab_ci.md index 44c9ff9b..0051f808 100644 --- a/docs/gitlab_ci.md +++ b/docs/gitlab_ci.md @@ -1,3 +1,8 @@ +--- +title: GitLab CI Integration +category: 62cdf6722c2c1602a4b69643 +hidden: false +--- # GitLab CI Integration ## Overview @@ -29,11 +34,11 @@ thresholds. The GitLab CI 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](https://hub.docker.com/r/phylumio/phylum-ci/tags) -* A [GitLab token](https://docs.gitlab.com/ee/security/token_overview.html) with API access -* A [Phylum token](https://docs.phylum.io/docs/api-keys) with API access - * [Contact Phylum](https://phylum.io/contact-us/) or create an account and register to gain access - * See also [`phylum auth register`](https://docs.phylum.io/docs/phylum_auth_register) command documentation +* Access to the [phylumio/phylum-ci Docker image][docker_image] +* A [GitLab token][gitlab_tokens] with API access +* A [Phylum token][phylum_tokens] with API access + * [Contact Phylum][phylum_contact] or create an account and register to gain access + * See also [`phylum auth register`][phylum_register] command documentation * Consider using a bot or group account for this token * Access to the Phylum API endpoints * That usually means a connection to the internet, optionally via a proxy @@ -42,6 +47,12 @@ The pre-requisites for using this image are: * See [`phylum project`](https://docs.phylum.io/docs/phylum_project) and [`phylum project create`](https://docs.phylum.io/docs/phylum_project_create) command documentation +[docker_image]: https://hub.docker.com/r/phylumio/phylum-ci/tags +[gitlab_tokens]: https://docs.gitlab.com/ee/security/token_overview.html +[phylum_tokens]: https://docs.phylum.io/docs/api-keys +[phylum_contact]: https://phylum.io/contact-us/ +[phylum_register]: https://docs.phylum.io/docs/phylum_auth_register + ## Configure `.gitlab-ci.yml` Phylum analysis of dependencies can be added to existing CI workflows or on it's own with this minimal configuration: @@ -98,7 +109,7 @@ is created for each release of the `phylum-ci` Python package and _should_ not c 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 `phylumio/phylum-ci` -[tags on Docker Hub](https://hub.docker.com/r/phylumio/phylum-ci/tags) or with the command: +[tags on Docker Hub][docker_image] or with the command: ```sh # NOTE: The command-line JSON processor `jq` is used here for the sake of a one line example. It is not required. @@ -139,16 +150,16 @@ A GitLab token with API access is required to use the API (e.g., to post notes/c This can be a personal, project, or group access token. The account used to create the token will be the one that appears to post the notes/comments on the merge request. Therefore, it might be worth looking into using a bot account, which is available for project and group access tokens. -See the [GitLab Token Overview](https://docs.gitlab.com/ee/security/token_overview.html) documentation for more info. +See the [GitLab Token Overview][gitlab_tokens] documentation for more info. Note, using `$CI_JOB_TOKEN` as the value will work in some situations because "API authentication uses the job token, by using the authorization of the user triggering the job." This is not recommended for anything other than temporary personal use in private repositories as there is a chance that depending on it will cause failures when attempting to do the same thing in different scenarios. -A [Phylum token](https://docs.phylum.io/docs/api-keys) with API access is required to perform analysis on project -dependencies. [Contact Phylum](https://phylum.io/contact-us/) or create an account and register to gain access. -See also [`phylum auth register`](https://docs.phylum.io/docs/phylum_auth_register) command documentation and consider +A [Phylum token][phylum_tokens] with API access is required to perform analysis on project +dependencies. [Contact Phylum][phylum_contact] or create an account and register to gain access. +See also [`phylum auth register`][phylum_register] command documentation and consider using a bot or group account for this token. The values for the `GITLAB_TOKEN` and `PHYLUM_API_KEY` variables can come from a @@ -182,7 +193,7 @@ to protect them appropriately**. The script arguments to the Docker image are the way to exert control over the execution of the Phylum analysis. The `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](../README.md#usage) or view the +output as specified in the [Usage section of the top-level README.md][usage] or view the [source code](https://github.com/phylum-dev/phylum-ci/blob/main/src/phylum/ci/cli.py) directly. ```yaml @@ -223,8 +234,12 @@ output as specified in the [Usage section of the top-level README.md](../README. ## Alternatives -It is also possible to make direct use of the [`phylum` Python package](https://pypi.org/project/phylum/) 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](../README.md#installation) and [Usage](../README.md#usage) sections of the [README file](../README.md) -for more detail. +It is also possible to make direct use of the [`phylum` Python package][pypi] 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][installation] and [Usage][usage] sections of the [README file][readme] for more detail. + +[pypi]: https://pypi.org/project/phylum/ +[readme]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md +[installation]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md#installation +[usage]: https://github.com/phylum-dev/phylum-ci/blob/main/README.md#usage diff --git a/docs/integrations_overview.md b/docs/integrations_overview.md new file mode 100644 index 00000000..434df061 --- /dev/null +++ b/docs/integrations_overview.md @@ -0,0 +1,33 @@ +--- +title: Integrations Overview +category: 62cdf6722c2c1602a4b69643 +hidden: false +--- +# Integrations + +Phylum is the future of software supply chain security and is eager to provide integrations across the diverse +set of environments and ecosystems used by developers. + +## Current Integrations + +The current Continuous Integration (CI) platforms/environments supported are: + +### GitHub Actions + +See the [GitHub Actions Integration documentation][github_docs] for more info. + +[github_docs]: https://docs.phylum.io/docs/github_actions + +### GitLab CI + +See the [GitLab CI Integration documentation][gitlab_docs] for more info. + +[gitlab_docs]: https://docs.phylum.io/docs/gitlab_ci + +## Future Integrations + +If there is an unsupported use case for managing the security of your dependencies, we want to know about it. +If there is a way Phylum can be used to make your life as a developer easier, we want to be there for you and do it! + +Please let us know what you need by either creating a [GitHub issue](https://github.com/phylum-dev/phylum-ci/issues) +or sending a note through the general [Contact Us](https://docs.phylum.io/docs/support) options. From b516a6e4ea24474e9844a2dc02b381259215b5d9 Mon Sep 17 00:00:00 2001 From: Charles Coggins Date: Wed, 13 Jul 2022 10:58:34 -0500 Subject: [PATCH 2/2] ci: syncronize integration doc updates for each release The new job added to the existing Release workflow was modeled after the one in the `phylum-dev/cli` repo. The organizational secret used for accessing the Readme.com platform was exposed to this repo and is ready for use. Closes #75 --- .github/workflows/release.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bbe6a838..f05df703 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -183,3 +183,16 @@ jobs: - name: Logout of Docker Hub if: always() run: docker logout + + docs: + name: Update the readme documentation + needs: release + runs-on: ubuntu-latest + steps: + - name: Checkout the repo + uses: actions/checkout@v3 + + - name: Update v2-latest using rdme + uses: readmeio/rdme@7.3.0 + with: + rdme: docs ./docs --key=${{ secrets.README_API }} --version=2-latest