Psalm GitHub Action 镜像文档

1. 镜像概述和主要用途

本镜像包含 Psalm 的官方 GitHub Actions，用于在 GitHub Actions 工作流中运行 Psalm 静态代码分析工具。主要用途是在自动化流程中对 PHP 项目进行静态代码检查，检测代码中的错误、潜在问题及安全漏洞，提升代码质量与安全性。

2. 核心功能和特性

• 版本指定：支持指定 Psalm 版本（3.14.2 及以上），确保分析环境一致性。
• 安全分析：集成 Psalm 安全分析功能，可生成安全漏洞报告，并支持上传至 GitHub Security 标签。
• Composer 自定义：支持配置是否安装 dev 依赖、忽略平台要求，以及指定 Composer 文件所在的相对目录。
• 私有仓库支持：通过 SSH 认证支持访问私有 Composer 仓库，兼容 GitHub、GitLab、Bitbucket 及自定义域名仓库。

3. 使用场景和适用范围

适用于在 GitHub Actions 工作流中对 PHP 项目执行自动化静态代码分析的场景，尤其适合需要：

• 自动化检测代码语法错误、类型问题及逻辑缺陷；
• 持续监控项目安全漏洞并集中管理（通过 GitHub Security 标签）；
• 对使用 Composer 管理依赖的 PHP 项目（含私有依赖仓库）进行标准化分析。

4. 使用方法和配置说明

4.1 基本使用方法

在 GitHub Actions 工作流中添加 Psalm 分析步骤，基础配置如下：

name: Psalm Static Analysis
on: [push, pull_request]

jobs:
  psalm:
    name: Psalm
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run Psalm
        uses: docker://ghcr.io/psalm/psalm-github-actions

4.2 指定 Psalm 版本

可通过镜像标签指定 Psalm 版本（需 3.14.2 及以上版本）：

- name: Run Psalm
  uses: docker://ghcr.io/psalm/psalm-github-actions:5.7.7  # 指定版本为 5.7.7

4.3 安全分析配置

4.3.1 基础安全分析

启用安全分析并生成报告：

- name: Run Psalm with Security Analysis
  uses: docker://ghcr.io/psalm/psalm-github-actions
  with:
    security_analysis: true  # 启用安全分析

4.3.2 上传至 GitHub Security 标签

将安全分析结果以 SARIF 格式上传至 GitHub Security 标签，便于团队集中查看：

- name: Run Psalm with Security Analysis
  uses: docker://ghcr.io/psalm/psalm-github-actions
  with:
    security_analysis: true
    report_file: results.sarif  # 指定 SARIF 报告文件路径

- name: Upload Security Results to GitHub
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif  # 上传生成的 SARIF 文件

4.4 Composer 自定义配置

4.4.1 安装 Dev 依赖与忽略平台要求

默认不安装 dev 依赖且检查平台要求，可通过以下配置修改：

- name: Run Psalm with Custom Composer Config
  uses: docker://ghcr.io/psalm/psalm-github-actions
  with:
    composer_require_dev: true  # 安装 dev 依赖（默认 false）
    composer_ignore_platform_reqs: true  # 忽略平台要求（默认 false）

4.4.2 指定相对目录

若 composer.json 不在项目根目录，可通过 relative_dir 指定相对路径：

- name: Run Psalm in Subdirectory
  uses: docker://ghcr.io/psalm/psalm-github-actions
  with:
    relative_dir: ./subdir  # Composer 文件所在的相对目录

4.5 私有 Composer 仓库认证

访问私有 Composer 仓库需通过 SSH 认证，配置步骤如下：

1. 生成 SSH 密钥对（仅授予只读权限），添加公钥至私有仓库（如 GitHub Deploy Keys）。
2. 将私钥和公钥存储为 GitHub Secrets。
3. 在工作流中传入密钥及可选的自定义域名：

- name: Run Psalm with Private Repo Access
  uses: docker://ghcr.io/psalm/psalm-github-actions
  with:
    ssh_key: ${{ secrets.PRIVATE_SSH_KEY }}  # 私有 SSH 密钥（必填）
    ssh_key_pub: ${{ secrets.PUBLIC_SSH_KEY }}  # 公钥（必填）
    ssh_domain: my-custom-git.com  # 自定义仓库域名（可选，默认支持 github.com、gitlab.com、bitbucket.org）

5. 配置参数说明