search

github / licensed-ci

Update and check cached licenses in a GitHub Actions workflow
MIT License
39 stars 7 forks source link

readme

licensed-ci

test

A GitHub Action to run github/licensed in a CI workflow.

  1. Run a workflow to update cached dependency metadata using licensed cache and push updates to GitHub
  2. Run licensed status to check that license data is available, known, up to date and valid for all dependencies
    • Status check failures will cause the step to fail, allowing examination and further updates to the code (if needed).

Available Workflows

Push (push)

This is the default workflow and the behavior in v1.1.0.

Update cached dependency metadata on the target branch and push changes to origin. If pr_comment input is set and a pull request is available, a comment is added to the pull request. This input is deprecated and will be removed in the next major version.

Branch (branch)

Update cached dependency metadata on a branch named <branch>-licenses and opens a pull request to merge the changes into the target branch. If pr_comment input is set, it will be added to the body text when creating the pull request. This input is deprecated and will be removed in the next major version.

Manual adjustments to license data or the github/licensed configuration should happen on the new licenses branch. Any runs of the action on a *-licenses branch will run status checks only - dependency metadata will not be updated.

Notes:

Push for changes from bots, Branch for changes from users (push_for_bots)

This is a hybrid workflow, choosing either the branch or push workflow depending on the context that triggered licensed-ci. The intended result is that dependency changes made by bots will run the push workflow, while dependency changes initiated by humans will run the branch workflow. Choosing the push workflow for changes made by bots requires less human interaction overall in reviewing and merging multiple pull requests.

The workflow that is run is chosen based on a few different checks:

  1. If the branch workflow has already created a *-licenses branch, continue to use the branch workflow
  2. If the action payload's sender field is for a user account, use the branch workflow
  3. If the above checks don't pass, use the push workflow

Configuration

Outputs

Usage

See a full example below.

Supported Events

This action supports the push, pull_request, workflow_dispatch, and scheduled events. When using push, the action workflow should include tags-ignore: '**' to avoid running the action on pushed tags. New tags point to code but do not represent new or changed code that could include updated dependencies.

on:
  # run on pushes to the default branch
  push:
    branches:
      - main
    tags-ignore: '**'
  # run on pull request events with changes to code
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
  # run on demand
  workflow_dispatch:
  # run on a schedule against the repository's default branch
  schedule:
    - cron: '0 8 * * *' # run every day at 8am

Basic Ruby usage using Bundler + Gemfile

jobs:
  licensed:
    env: # optionally configure the Gemfile used
      BUNDLE_GEMFILE: ${{ github.workspace }}/licensed.gemfile
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1
          bundler-cache: true # improve performance on subsequent runs
          cache-version: 1
      - run: xxx # Install project dependencies here.
      - uses: github/licensed-ci@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          command: "bundle exec licensed" # or bin/licensed when using binstubs

Basic non-Ruby usage using github/setup-licensed

jobs:
  licensed:
    steps:
      - uses: actions/checkout@v3

      # install licensed.  licensed v4 can only be installed as a gem and requires
      # running ruby/setup-ruby before github/setup-licensed.  If a project doesn't
      # require a specific version of ruby, default to installing latest stable
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ruby
      - uses: github/setup-licensed@v1
        with:
          version: 4.x

      - run: xxx # Install project dependencies here.
      - uses: github/licensed-ci@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Using outputs to make a PR comment

jobs:
  licensed:
    steps:
      - # environment setup ...
      - id: licensed # save the id of the step to reference later
        uses: github/licensed-ci@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - uses: actions/github-script@0.2.0
        if: always() && steps.licensed.outputs.pr_number
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            github.issues.createComment({
              ...context.repo,
              issue_number: ${{ steps.licensed.outputs.pr_number }}
              body: 'My custom PR message'
            })

Authentication

Accessing private repositories during the licensed-ci action

The default GITHUB_TOKEN authentication token provided by GitHub Actions does not have read access to any other GitHub repositories. If running github/licensed in your repo requires access to a private GitHub repository, please set the github_token workflow input to a PAT from a user with access to necessary private repositories.

Using licensed-ci with permission restrictions on GITHUB_TOKEN

If your action workflow restricts which permissions are granted to GITHUB_TOKEN, please ensure that both contents and pull-requests are set to write. As part of an Actions workflow, licensed-ci can push license metadata file updates to a repo, comment on existing PRs, and open new PRs.

permissions:
  pull-requests: write
  contents: write

Full Node.js example

on:
  # run on pushes to the default branch
  push:
    branches:
      - main
  # run on pull request events with changes to code
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
  # run on demand
  workflow_dispatch:

# ensure that the action can push changes to the repo and edit PRs
# when using `secrets.GITHUB_TOKEN`
permissions:
  pull-requests: write
  contents: write

jobs:
  licensed:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # install environment pre-requisites and project dependencies
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm # cache dependencies for faster subsequent runs.
      - run: npm install --production --ignore-scripts

      # install licensed.  licensed v4 can only be installed as a gem and requires
      # running ruby/setup-ruby before github/setup-licensed.  If a project doesn't
      # require a specific version of ruby, default to installing latest stable
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ruby
      - uses: github/setup-licensed@v1
        with:
          version: 4.x

      - id: licensed
        uses: github/licensed-ci@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - uses: actions/github-script@0.2.0
        if: always() && steps.licensed.outputs.pr_number
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            github.issues.createComment({
              ...context.repo,
              issue_number: ${{ steps.licensed.outputs.pr_number }}
              body: 'My custom PR message'
            })

License

This project is released under the MIT License

Maintainers

Support

You can expect the following support. See SUPPORT for more information.

Contributions

Contributions are welcome! See CONTRIBUTING.md for more information on how to get involved.

Acknowledgement

Huge thank you and appreciation to @jonabc for championing license compliance and maintaining licensed over the years.