apache/skywalking-eyes

SkyWalking Eyes

镜像概述和主要用途

SkyWalking Eyes 是一个功能全面的许可证工具，旨在帮助开发团队确保源代码的许可证合规性。它能够检查源代码文件中的许可证头是否正确，自动修复缺失或不正确的许可证头，并解析项目依赖项的许可证信息，进行兼容性检查。该工具支持多种使用方式，包括 GitHub Actions 集成、Docker 镜像运行以及本地编译执行，适用于各类开源和商业项目的许可证管理流程。

核心功能和特性

• 许可证头管理：检查源代码文件是否包含正确的许可证头，支持自动修复缺失或格式不正确的许可证头
• 依赖项许可证解析：识别项目依赖项的许可证类型，支持自动检查依赖项许可证与主项目许可证的兼容性
• 灵活配置：通过配置文件自定义检查路径、忽略文件、许可证内容等
• 多环境支持：可集成到 GitHub Actions 工作流，通过 Docker 镜像运行，或本地编译使用
• SPDX 标准支持：支持 SPDX 许可证标识符，简化标准许可证的配置流程

使用场景和适用范围

• 开源项目的许可证合规性检查，确保所有源代码文件包含正确的许可证头
• CI/CD 流程集成，在代码提交或 PR 阶段自动执行许可证检查，防止不合规代码合并
• 依赖项管理，审计项目依赖的第三方库许可证，避免引入不兼容许可证的依赖
• 大型项目的批量许可证头修复，减少手动操作成本

详细使用方法和配置说明

GitHub Actions 集成

在 GitHub Actions 工作流中添加步骤，实现代码提交时自动检查许可证头：

yaml
- name: 检查许可证头
  uses: apache/skywalking-eyes@main      # 建议使用具体版本号而非main分支
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # 如需在PR上评论检查结果则必须设置
  # with:
      # 可选：设置日志级别，默认info
      # log: debug
      # 可选：指定配置文件路径，默认.licenserc.yaml
      # config: .licenserc.yaml

在项目根目录创建 .licenserc.yaml 配置文件，Apache 软件基金会项目可使用以下基础配置：

yaml
header:
  license:
    spdx-id: Apache-2.0
    copyright-owner: Apache Software Foundation

  paths-ignore:
    - 'dist'
    - 'licenses'
    - '**/*.md'
    - 'LICENSE'
    - 'NOTICE'

  comment: on-failure

完整配置说明参见 配置部分。

Docker 镜像使用

官方 Docker 镜像

使用 Docker 镜像执行许可证头检查和修复：

shell
# 检查许可证头
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header check

# 修复许可证头
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix

最新代码 Docker 镜像

对于希望测试 main 分支最新代码的用户和开发者，每个 main 分支提交会发布镜像到 GitHub Container Registry，标记为提交 SHA 值，最新提交同时标记为 latest。

注意：这些镜像非 Apache 官方发布版本。官方发布请参考 下载页面 获取二进制文件，或 https://hub.docker.com/r/apache/skywalking-eyes 获取官方镜像。

shell
# 检查许可证头（最新代码镜像）
docker run -it --rm -v $(pwd):/github/workspace ghcr.io/apache/skywalking-eyes/license-eye header check

# 修复许可证头（最新代码镜像）
docker run -it --rm -v $(pwd):/github/workspace ghcr.io/apache/skywalking-eyes/license-eye header fix

从源代码编译

手动编译并使用：

bash
# 克隆仓库
git clone https://github.com/apache/skywalking-eyes
cd skywalking-eyes

# 编译
make build

检查许可证头

bash
bin/darwin/license-eye -c test/testdata/.licenserc_for_test_check.yaml header check

INFO 从文件加载配置: test/testdata/.licenserc_for_test_check.yaml 
INFO 共检查30个文件，有效: 12, 无效: 12, 忽略: 6, 已修复: 0 
ERROR 以下文件缺少有效的许可证头: 
test/testdata/include_test/without_license/testcase.go
test/testdata/include_test/without_license/testcase.graphql
...
exit status 1

修复许可证头

bash
bin/darwin/license-eye -c test/testdata/.licenserc_for_test_fix.yaml header fix

INFO 从文件加载配置: test/testdata/.licenserc_for_test_fix.yaml
INFO 共检查20个文件，有效: 10, 无效: 10, 忽略: 0, 已修复: 10 

解析依赖项许可证

辅助人工审计依赖项许可证，命令始终返回0：

bash
bin/darwin/license-eye -c test/testdata/.licenserc_for_test_check.yaml dep resolve
INFO 未设置GITHUB_TOKEN，license-eye不会在PR上评论
INFO 从文件加载配置: test/testdata/.licenserc_for_test_check.yaml
WARNING 无法解析依赖项许可证: gopkg.in/yaml.v3 cannot identify license content
依赖项                                  |      许可证
------------------------------------------- | ------------
github.com/bmatcuk/doublestar/v2            |          MIT
github.com/sirupsen/logrus                  |          MIT
...
gopkg.in/yaml.v3                            |      Unknown

ERROR 无法识别以下包的许可证:
gopkg.in/yaml.v3

检查依赖项许可证

自动检查依赖项许可证兼容性，发现不兼容许可证时返回1：

bash
bin/darwin/license-eye -c test/testdata/.licenserc_for_test_check.yaml dep check
INFO 未设置GITHUB_TOKEN，license-eye不会在PR上评论 
INFO 从文件加载配置: .licenserc.yaml 
WARNING 无法解析依赖项许可证 <github.com/gogo/protobuf>: cannot identify license content 
...
ERROR 以下许可证与主许可证Apache-2.0不兼容: 
License: Unknown Dependency: github.com/gogo/protobuf
...
exit status 1

配置说明

完整配置文件示例：

yaml
header:  # <1>
  license:
    spdx-id: Apache-2.0  # <2>
    copyright-owner: Apache Software Foundation  # <3>
    content: |  # <4>
      Licensed to Apache Software Foundation (ASF) under one or more contributor
      license agreements. See the NOTICE file distributed with
      this work for additional information regarding copyright
      ownership. Apache Software Foundation (ASF) licenses this file to you under
      the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing,
      software distributed under the License is distributed on an
      "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
      KIND, either express or implied.  See the License for the
      specific language governing permissions and limitations
      under the License.

    pattern: |  # <5>
      Licensed to the Apache Software Foundation under one or more contributor
      license agreements. See the NOTICE file distributed with
      this work for additional information regarding copyright
      ownership. The Apache Software Foundation licenses this file to you under
      the Apache License, Version 2.0 \(the "License"\); you may
      not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing,
      software distributed under the License is distributed on an
      "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
      KIND, either express or implied.  See the License for the
      specific language governing permissions and limitations
      under the License.

  paths:  # <6>
    - '**'

  paths-ignore:  # <7>
    - 'dist'
    - 'licenses'
    - '**/*.md'
    - '**/testdata/**'
    - '**/go.mod'
    - '**/go.sum'
    - 'LICENSE'
    - 'NOTICE'
    - '**/assets/languages.yaml'
    - '**/assets/assets.gen.go'

  comment: on-failure  # <8>

dependency:  # <9>
  files:  # <10>
    - go.mod

1. header 部分：源代码许可证头的配置。
2. license.spdx-id：许可证的 SPDX ID，使用标准SPDX许可证时可简化配置，无需复制完整许可证内容，fix命令会使用此许可证模板插入头信息。
3. license.copyright-owner：版权所有者，用于替换SPDX许可证模板中的[owner]占位符。
4. license.content：自定义许可证文本，当不使用标准许可证时可在此粘贴，fix命令会使用此内容插入头信息。若同时指定content和spdx-id，content优先级更高。
5. license.pattern：可选正则表达式，当许可证头与content或SPDX标准文本不完全一致时，用于匹配许可证文本。
6. paths：需要检查（和修复）的路径列表，默认['**']，支持**/*.md、**/bin/**等格式。
7. paths-ignore：忽略检查的路径列表，默认包含.git目录和.gitignore中的内容。
8. comment：PR评论触发条件，可选on-failure（失败时）、always（始终）或never（从不）。除never外，需设置GITHUB_TOKEN环境变量。
9. dependency部分：依赖项许可证解析的配置。
10. dependency.files：声明项目依赖的文件列表，如Go项目的go.mod、Maven项目的pom.xml等，相对路径相对于.licenserc.yaml。

注意：当spdx-id为Apache-2.0且所有者为Apache Software Foundation时，内容将使用ASF专用许可证文本；其他情况使用标准许可证文本。

支持的文件类型

header check 命令理论上支持所有文件类型，header fix 命令支持的文件类型可在 languages.yaml 中查看。若语言配置中comment_style_id非空且在 comment styles文件 中定义，则支持fix命令。

技术文档

• 活动图 详细解释了许可证头修复机制，源文件见 header_fix_logic.plantuml。

贡献方式

• 如发现应支持但未包含的文件类型，可通过 https://github.com/apache/skywalking-eyes/pulls 添加配置到上述两个文件。
• 如发现未支持的SPDX ID许可证模板，可通过 https://github.com/apache/skywalking-eyes/pulls 添加到 模板文件夹。

许可证

https://github.com/apache/skywalking-eyes/blob/master/LICENSE

联系我们

• 提交 issue：标题前缀使用 [INFRA]，访问 https://github.com/apache/skywalking/issues/new%E3%80%82
• 邮件列表：*******，发送邮件至 *** 并按照回复订阅。
• Slack：加入 Apache Slack 的 skywalking 频道，链接失效时可在 Apache INFRA WIKI 获取最新邀请链接。
• ***：ASFSkyWalking