eclipse-ipa 0.3.0

Tool to perform IP Analysis of GitHub and GitLab repositories.

Eclipse IP Analysis

About

Eclipse IP Analysis (IPA) enables seamless third-party dependency analysis in GitLab and GitHub repositories and groups/organizations using the Eclipse Dash License Tool. As default output, it generates a comprehensive HTML report with the results.

List of currently supported programming languages: Go, Java (Maven and Gradle), JavaScript (NPM and Yarn), TypeScript (NPM and Yarn), Kotlin (Gradle), Python (PyPi and Conda).

Getting Started

Base Requirements

To run the tool, you must install the base requirements described below.

• Python >=3.10: check your Python version with the command python3 --version. Also, check that you have the Python Package Manager (pip) installed. Similar to Python, you can run pip3 --version. The resulting line should contain your version of Python at its end. If pip is not installed, official documentation can be followed here.

• Java JDK 11 or above: the latest version can be safely installed. Check that Java is installed and what's the current version by running the command java --version.

• Apache Maven: the latest version can be safely installed. Check that Maven is installed and what's the current version by running the command mvn --version.

• Git CLI: the latest version can be safely installed. Check that Git is installed and what's the current version by running the command git --version.

Install

pip3 install eclipse-ipa

Build from Source (Optional)

• Clone this repository using your favorite Git software or the command line. For the command line, please execute:

git clone https://gitlab.eclipse.org/eclipse/technology/dash/ip-analysis.git

• Navigate to the directory of the repository that you just cloned.
• Get Hatch to build the tool (https://hatch.pypa.io/latest/install).
• Build and install the tool:

hatch build
pip3 install dist/eclipse_ipa-*.whl

(back to top)

Usage

Run the tool with the following command:

eclipse-ipa [-h] [-ci | -e ECLIPSE_PROJECT | -gh | -gl GITLAB]

[--gh-token GH_TOKEN] [--gl-token GL_TOKEN] [-v] [-b BRANCH]

[-df DEPENDENCIES_FILE] [-ex EXCLUDE [EXCLUDE ...]] [-g GROUP]

[-p PROJECT] [-pf PROJECTS_FILE] [-r [REVIEW]] [-c CONFIG] [-l] [-s]

The tool does not require any of its arguments. However, a minimum set is needed to execute simple IP analysis if a configuration file is not specified.

A summary of the arguments is given below:

options:
  -h, --help            show this help message and exit
  -ci, --ci-mode        Execute in CI mode (default: False)
  -e, --eclipse-project ECLIPSE_PROJECT
                        Execute for specific Eclipse Project ID (default:
                        None)
  -gh, --github         Execute for GitHub (default: False)
  -gl, --gitlab GITLAB  Execute for GitLab URL (default: gitlab.eclipse.org)
  --gh-token GH_TOKEN   GitHub token (Defaults to GITHUB_TOKEN env var)
  --gl-token GL_TOKEN   GitLab token (Defaults to GITLAB_TOKEN env var)
  -v, --version         show the version and exit

Input & Scoping:
  -b, --branch BRANCH   Branch to analyze (Defaults to default branch on each
                        repository)
  -df, --dependencies-file DEPENDENCIES_FILE
                        File with dependencies to analyze (default: None)
  -ex, --exclude EXCLUDE [EXCLUDE ...]
                        Subgroups or repositories to exclude (default: None)
  -g, --group GROUP     GitHub Organization or GitLab Group to analyze
                        (default: None)
  -p, --project PROJECT
                        Specific project/repository to analyze (default: None)
  -pf, --projects-file PROJECTS_FILE
                        File containing list of projects/repositories to analyze (default:
                        None)
  -r, --review [REVIEW]
                        Eclipse Project ID for IP review (default: None)

Configuration & Analysis:
  -c, --config CONFIG   Configuration file to use (default: config.ini)
  -l, --declared-licenses
                        Retrieve declared licenses from package repositories
                        (default: False)

Output:
  -s, --summary         Output as an Eclipse Dash summary file (default:
                        False)

To start using the tool, you must provide one of the following six options:

1. An Eclipse Project ID (e.g., technology.dash). This is specified with option -e as summarized above.

2. A file with the dependencies to analyze (one per line) using the format supported by Eclipse Dash. The full path of this file is specified with option -df as summarized above.

3. A file with the list of GitHub/GitLab Projects to analyze. Each line should contain the GitHub/GitLab project complete name with namespace or URL. The full path of this file is specified with option -pf as summarized above.

Example for a GitHub line:

kubernetes-client/python

Example for a GitLab line:

eclipse/technology/dash/ip-analysis

4. A GitHub Organization, or a GitLab Group. Provide name with namespace or URL. This is specified with option -g as summarized above.

5. A GitHub Project, or a GitLab Project. Provide name with namespace or URL. This is specified with option -p as summarized above.

6. A configuration file, specified with option -c as summarized above. It allows additional customization, and a sample is provided in the same folder as the tool with the filename config.ini.sample. Parameters within the config file are described in the comments.

Please note that, for GitHub API public access, the API rate limits are very low. It's highly recommended to provide an access token in such cases.

Usage Examples

Run for a GitHub repository:

eclipse-ipa -gh --gh-token <GitHub Token> -p eclipse-dash/dash-licenses

Run for a GitHub organization:

eclipse-ipa -gh --gh-token <GitHub Token> -g eclipse-dash

IMPORTANT: It's highly recommended to use a GitHub token to have higher API rate limits for GitHub projects.

Run for a GitLab project:

eclipse-ipa -gl gitlab.eclipse.org -p eclipse/technology/dash/ip-analysis

Run for a GitLab group:

eclipse-ipa -gl gitlab.eclipse.org -g eclipse/technology/dash

Run for an Eclipse project (can have both GitHub and GitLab projects):

eclipse-ipa --gh-token <GitHub Token> -e technology.dash

IMPORTANT: It's highly recommended to use a GitHub token to have higher API rate limits for GitHub projects.

Run for an Eclipse project and enable Automatic IP Team Review Requests:

eclipse-ipa --gh-token <GitHub Token> --gl-token <GitLab Token> -e technology.dash -r

NOTE: A GitLab token is required for Automatic IP Team Review Requests (-r). For this example, the Eclipse Project ID will be re-used from the provided Eclipse Project (-e).

How the tool works

If a GitHub Organization/GitLab Group or a list of GitHub/GitLab Projects is provided, the tool fetches the programming languages for each project and searches for dependency files for each supported programming language. Once a list of dependency locations is found, it runs Eclipse Dash on those dependencies to analyze their IP approval status.

At the end, and by default, the tool outputs a full report in HTML. Any additional details can be found in the log file (ip-analysis.log).

(back to top)

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0, which is available at http://www.eclipse.org/legal/epl-2.0.

(back to top)