Skip to content

Latest commit

 

History

History
144 lines (85 loc) · 7.74 KB

check-go-dependencies-task.md

File metadata and controls

144 lines (85 loc) · 7.74 KB
Raw

"Check Go Dependencies" workflow (Task)

Use Licensed to check if the Go project has dependencies with incompatible licenses.

Licensed detects all dependencies of the project, detects their license types, and then checks them against a dependency license approval configuration.

There are several options for configuring approvals. The most useful being:

  • Allowed licenses - allow any dependency that has this license type.
  • Reviewed dependency - allow specific dependencies that don't pass the global allowed license configuration, but have been individually reviewed and found acceptable.

Installation

Workflow

Install the check-go-dependencies-task.yml GitHub Actions workflow to .github/workflows/

Assets

  • Taskfile.yml - tasks to cache metadata for and check compatibility of dependency licenses.
    • Install to: repository root (or merge into the existing Taskfile.yml).
  • Taskfile.yml - tasks to check Go dependencies.
    • Install to: repository root (or merge into the existing Taskfile.yml).
  • `.licensed.yml - suggested allowed dependency license types list for the project's license type.
    • Install to: repository root.

Configuration

The Licensed tool is configured via .licensed.yml configuration file, located in the repository root folder:

https://github.com/github/licensed/blob/master/docs/configuration.md

Project paths

By default, the project in the root of the repository will be checked. If the project is in a subfolder of the repository or if the repository contains multiple projects with dependencies that should be checked then the path to each project should be defined via apps[*].source_path keys in .licensed.yml.

Allowed licenses

A list of allowed license types can be defined in the .licensed.yml configuration file under:

  • The allowed key to apply to all projects.
  • The apps[*].allowed key to apply to a specific project.

All dependencies that are determined to use one of these licenses will be automatically allowed.

SPDX license identifiers are used, except converted to all lowercase letters (e.g., use gpl-3.0-or-later for the GPL 3.0 (or later) license).

Metadata cache

Dependency license metadata is stored in the .licenses folder. This should be committed to the repository. Generate or update the cache by running this command:

task general:cache-dep-licenses

Alternatively, you can download the dep-licenses-cache workflow artifact that is generated by the "Check Go Dependencies" workflow run when the cache is found to be outdated by the workflow's "check-cache" job.

Unrecognized licenses

Licensed uses the licensee tool to automatically detect the license type of the dependency. This will not be possible if a dependency author has not documented the license in a standardized fashion. In this case, the dependency licensing must be manually reviewed. licensee is a useful tool for this manual review process (use licensee --diff).

Once the license type has been determined, find the dependency's metadata file under the .licenses folder and update its license key with the SPDX license identifier of the dependency's license, converted to all lowercase letters. If the file containing the license was not found by Licensed, define its path in the licenses[*].sources key and add the text of the license in licenses[*].text. This will allow Licensed to check if the license has changed when the dependency version is updated.

Reviewed dependencies

A dependency might use a license type that can not be allowed globally via the allowed key of the .licensed.yml configuration file, but that is determined to be acceptable for that specific dependency.

In this case, the dependency's identifier must be added to the reviewed.<source ID>[*] key in the .licensed.yml configuration file.

Documentation

Readme badge

Markdown badge:

[![Check Go Dependencies status](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-go-dependencies-task.yml/badge.svg)](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-go-dependencies-task.yml)

Replace the TODO_REPO_OWNER and TODO_REPO_NAME placeholders in the URLs with the final repository owner and name (example).

Asciidoc badge:

image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-go-dependencies-task.yml/badge.svg["Check Go Dependencies status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-go-dependencies-task.yml"]

Define the {repository-owner} and {repository-name} attributes and use them throughout the readme (example).

Development Guide

Add the following under the "Running Checks" section of the project's development documentation (template available here):

### Dependency License Metadata

Metadata about the license types of all dependencies is cached in the repository. To update this cache, run the following command from the repository root folder:

```text
task general:cache-dep-licenses
```

The necessary **Licensed** tool can be installed by following [these instructions](https://github.com/github/licensed#as-an-executable).

Unfortunately, **Licensed** does not have Windows support.

An updated cache is also generated whenever the cache is found to be outdated by the by the "**Check Go Dependencies**" CI workflow and made available for download via the `dep-licenses-cache` [workflow artifact](https://docs.github.com/actions/managing-workflow-runs/downloading-workflow-artifacts).

Commit message

Add CI workflow to check for unapproved Go dependency licenses

A task and GitHub Actions workflow are provided here for checking the license types of Go project dependencies.

On every push and pull request that affects relevant files, the CI workflow will check:

- If the dependency licenses cache is up to date
- If any of the project's dependencies have an unapproved license type.

Approval can be based on:

- Universally allowed license type
- Individual dependency

PR message

A task and GitHub Actions workflow are provided here for checking the license types of Go project dependencies.

On every push and pull request that affects relevant files, the CI workflow will use [**Licensed**](https://github.com/github/licensed) to check:

- If the dependency licenses cache is up to date
- If any of the project's dependencies have an unapproved license type.

Approval can be based on:

- [Allowed license type](https://github.com/github/licensed/blob/master/docs/configuration/allowed_licenses.md)
- [Individual dependency](https://github.com/github/licensed/blob/master/docs/configuration/reviewing_dependencies.md)