Skip to content

Commit 42016b9

Browse files
cd-workcd-work
authored
Add Maven repository proxy documentation (#217)
1 parent 37772bc commit 42016b9

File tree

3 files changed

+101
-0
lines changed

3 files changed

+101
-0
lines changed

‎docs/artifact_repositories/about.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Phylum registry URLs under which they are hosted:
1717
| Ecosystem | Phylum Registry URL |
1818
| --------- | -------------------------------- |
1919
| Cargo | <https://cargo.phylum.io/> |
20+
| Maven | <https://maven.phylum.io/> |
2021
| NPM | <https://npm.phylum.io/> |
2122
| PyPI | <https://pypi.phylum.io/simple/> |
2223
| RubyGems | <https://rubygems.phylum.io/> |
@@ -37,6 +38,7 @@ registries:
3738
| Ecosystem | Information Link |
3839
| --------- | ------------------------- |
3940
| Cargo | [Documentation][Cargo] |
41+
| Maven | [Documentation][Maven] |
4042
| NPM | [Documentation][NPM] |
4143
| PyPI | [Documentation][PyPI] |
4244
| RubyGems | [Documentation][RubyGems] |
@@ -49,6 +51,7 @@ receive those notifications, you can [setup webhooks].
4951
[setup webhooks]: ./api.md#webhooks
5052
[Artifactory]: ./artifactory.md
5153
[Cargo]: ./cargo.md
54+
[Maven]: ./maven.md
5255
[NPM]: ./npm.md
5356
[PyPI]: ./pypi.md
5457
[RubyGems]: ./rubygems.md

‎docs/artifact_repositories/maven.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Phylum Maven Registry
2+
3+
The Phylum Maven registry is based on [Maven central].
4+
5+
[Maven central]: https://maven.apache.org/repositories/index.html
6+
7+
## Configuration
8+
9+
All configuration options will require a Phylum API key, since Phylum requires
10+
authentication. You can find out how to generate one in our
11+
[API Keys documentation].
12+
13+
In the following examples, all API keys will be represented as
14+
`<PHYLUM_API_KEY>`, so make sure to replace them with your generated key.
15+
16+
Additionally, if the default [policy] is not sufficient, a group can be passed
17+
to evaluate all packages against the group's policy. To do this, just replace
18+
`<PHYLUM_GROUP>` with the desired group name. The supplied API key **must** have
19+
access to this group.
20+
21+
If Phylum's default [policy] is sufficient, you can remove all instances of
22+
`<PHYLUM_GROUP>`.
23+
24+
[API Keys documentation]: ../knowledge_base/api-keys.md#generate-an-api-key
25+
[policy]: ../knowledge_base/policy.md
26+
27+
### `mvn`
28+
29+
The Phylum authorization header expects a token in Base64, so you first need to
30+
convert your Phylum group and API key:
31+
32+
```sh
33+
printf "<PHYLUM_GROUP>:<PHYLUM_API_KEY>" | base64
34+
```
35+
36+
> ⚠️ **WARNING** ⚠️
37+
>
38+
> Do not accidentally save your token into your shell history.
39+
40+
Custom Maven registries can be configured in the `${user.home}/.m2/settings.xml`
41+
file. Replace `[BASE64_OUTPUT]` in this XML with the token you've created in the
42+
previous step:
43+
44+
```xml
45+
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
46+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
47+
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
48+
http://maven.apache.org/xsd/settings-1.0.0.xsd">
49+
<servers>
50+
<server>
51+
<id>phylum</id>
52+
<configuration>
53+
<httpHeaders>
54+
<property>
55+
<name>Authorization</name>
56+
<value>Basic [BASE64_OUTPUT]</value>
57+
</property>
58+
</httpHeaders>
59+
</configuration>
60+
</server>
61+
</servers>
62+
63+
<mirrors>
64+
<mirror>
65+
<id>phylum</id>
66+
<name>Phylum</name>
67+
<url>https://maven.phylum.io</url>
68+
<mirrorOf>central</mirrorOf>
69+
</mirror>
70+
</mirrors>
71+
</settings>
72+
```
73+
74+
A blocked package will show up in `mvn` output as missing:
75+
76+
```text
77+
[INFO] ------------------------------------------------------------------------
78+
[INFO] BUILD FAILURE
79+
[INFO] ------------------------------------------------------------------------
80+
[INFO] Total time: 6.871 s
81+
[INFO] Finished at: 2024-10-29T18:44:40+01:00
82+
[INFO] ------------------------------------------------------------------------
83+
[ERROR] Failed to execute goal on project demo: Could not collect dependencies for project io.phylum:demo:jar:1.0-SNAPSHOT
84+
[ERROR] Failed to read artifact descriptor for commons-io:commons-io:jar:2.17.0
85+
[ERROR] Caused by: The following artifacts could not be resolved: commons-io:commons-io:pom:2.17.0 (absent): Could not transfer artifact commons-io:commons-io:pom:2.17.0 from/to phylum (https://maven.phylum.io): status code: 424, reason phrase: Failed Dependency (424)
86+
[ERROR]
87+
[ERROR] -> [Help 1]
88+
[ERROR]
89+
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
90+
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
91+
[ERROR]
92+
[ERROR] For more information about the errors and possible solutions, please read the following articles:
93+
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyResolutionException
94+
```
95+
96+
If a version range is accepted by the manifest, the package manager will
97+
automatically attempt to use a version that passes Phylum's policy.

‎site/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ const sidebars = {
130130
items: [
131131
'artifact_repositories/artifactory',
132132
'artifact_repositories/cargo',
133+
'artifact_repositories/maven',
133134
'artifact_repositories/npm',
134135
'artifact_repositories/pypi',
135136
'artifact_repositories/rubygems',

0 commit comments

Comments
 (0)