# @actions/attest 中文文档

规范地址：https://npmcn.com/package/%40actions/attest/

版本：3\.2\.0
npm 元数据更新时间：2026-06-11T21:10:50.029Z
中文译文更新时间：2026-11-05T17:59:29.713Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40actions/attest
原文对照：https://npmcn.com/package/%40actions/attest/?lang=original
项目主页：https://github.com/actions/toolkit/tree/main/packages/attest
源码仓库：https://github.com/actions/toolkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：54.4 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2024-02-26T19:51:18.035Z
- 最新版本发布：2026-02-26T19:16:08.052Z
- 近 30 天下载量：115413（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 6 个）

## 中文简介

证明行动

## 安装

```sh
npm install @actions/attest
```

也可以使用：`pnpm add @actions/attest`、`yarn add @actions/attest`、`bun add @actions/attest`

## README

# `@actions/attest`

生成工作流程文物签名证明的功能.

证明将一些标的物(一种命名的文物及其文摘)绑入一个 使用 [转入 语句](https://github.com/in-toto/attestation/tree/main/spec/v1) 格式。 A 类 为证明书生成签名,使用 [西格斯托尔](https://www.sigstore.dev/)\- 签发了签名证书.

证书一经创建并签名,就会被上传到GH aPI证明和与工作流程所依据的存储库有关的证明 启动.

见 [利用文物证明确定建筑物的来源](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds) 有关文物证明的更多信息.

## 目录

-   [使用量](https://npmcn.com/package/%40actions/attest/#readme-usage)
    -   [证明](https://npmcn.com/package/%40actions/attest/#readme-attest)
    -   [证明书](https://npmcn.com/package/%40actions/attest/#readme-attestprovenance)
    -   [证明](https://npmcn.com/package/%40actions/attest/#readme-attestation)
-   [Sigstore 实例](https://npmcn.com/package/%40actions/attest/#readme-sigstore-instance)
-   [存储](https://npmcn.com/package/%40actions/attest/#readme-storage)

## 使用量

### `attest`

这个 `attest` 函数取所提供对象/相配对并生成 a 签名的证明.

```js
const { attest } = require('@actions/attest');
const core = require('@actions/core');

async function run() {
    // In order to persist attestations to the repo, this should be a token with
    // repository write permissions.
    const ghToken = core.getInput('gh-token');

    const attestation = await attest({
        subjects: [{name: 'my-artifact-name', digest: { 'sha256': '36ab4667...'}}],
        predicateType: 'https://in-toto.io/attestation/release',
        predicate: { . . . },
        token: ghToken
    });

    console.log(attestation);
}

run();
```

这个 `attest` 函数支持以下选项:

```typescript
export type AttestOptions = {
  // Deprecated. Use 'subjects' instead.
  subjectName?: string
  // Deprecated. Use 'subjects' instead.
  subjectDigest?: Record<string, string>
  // Collection of subjects to be attested
  subjects?: Subject[]
  // URI identifying the content type of the predicate being attested.
  predicateType: string
  // Predicate to be attested.
  predicate: object
  // GitHub token for writing attestations.
  token: string
  // Sigstore instance to use for signing. Must be one of "public-good" or
  // "github".
  sigstore?: 'public-good' | 'github'
  // HTTP headers to include in request to attestations API.
  headers?: {[header: string]: string | number | undefined}
  // Whether to skip writing the attestation to the GH attestations API.
  skipWrite?: boolean
}

export type Subject = {
   // Name of the subject.
  name: string
   // Digests of the subject. Should be a map of digest algorithms to their hex-encoded values.
  digest: Record<string, string>
}
```

### `attestProvenance`

这个 `attestProvenance` 函数接受一些文物的名称和摘要 生成一个基于这些值的建置出处证明.

证明书是首先生成的 [SLSA 来源 上游](https://slsa.dev/spec/v1.0/provenance) 居住人口 [元数据](https://github.com/slsa-framework/github-actions-buildtypes/tree/main/workflow/v1) 从 GitHub 动作运行中拉出 .

```js
const { attestProvenance } = require('@actions/attest');
const core = require('@actions/core');

async function run() {
    // In order to persist attestations to the repo, this should be a token with
    // repository write permissions.
    const ghToken = core.getInput('gh-token');

    const attestation = await attestProvenance({
        subjectName: 'my-artifact-name',
        subjectDigest: { 'sha256': '36ab4667...'},
        token: ghToken
    });

    console.log(attestation);
}

run();
```

这个 `attestProvenance` 函数支持以下选项:

```typescript
export type AttestProvenanceOptions = {
  // Deprecated. Use 'subjects' instead.
  subjectName?: string
  // Deprecated. Use 'subjects' instead.
  subjectDigest?: Record<string, string>
  // Collection of subjects to be attested
  subjects?: Subject[]
  // URI identifying the content type of the predicate being attested.
  token: string
  // Sigstore instance to use for signing. Must be one of "public-good" or
  // "github".
  sigstore?: 'public-good' | 'github'
  // HTTP headers to include in request to attestations API.
  headers?: {[header: string]: string | number | undefined}
  // Whether to skip writing the attestation to the GH attestations API.
  skipWrite?: boolean
  // Issuer URL responsible for minting the OIDC token from which the
  // provenance data is read. Defaults to
  // 'https://token.actions.githubusercontent.com".
  issuer?: string
}
```

### `Attestation`

这个 `Attestation` 返回时间 `attest`编号 :`attestProvenance` 有以下内容: 字段 :

```typescript
export type Attestation = {
  /*
   * JSON-serialized Sigstore bundle containing the provenance attestation,
   * signature, signing certificate and witnessed timestamp.
   */
  bundle: SerializedBundle
  /*
   * PEM-encoded signing certificate used to sign the attestation.
   */
  certificate: string
  /*
   * ID of Rekor transparency log entry created for the attestation (if
   * applicable).
   */
  tlogID?: string
  /*
   * ID of the persisted attestation (accessible via the GH API).
   */
  attestationID?: string
}
```

有关Sigstore捆绑格式的详情,见 [Bundle 原生纸 规格](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)。 。 。 .

### 创建Storage记录

这个 `createStorageRecord` 函数创建 [文物元数据存储记录](https://docs.github.com/en/rest/orgs/artifact-metadata?apiVersion=2022-11-28#create-artifact-metadata-storage-record) 代表一个经认证的文物。 它接受定义文物的参数 和包登记细节。 存储记录中包含关于该文物存放于特定包登记册的元数据.

```js
const { createStorageRecord } = require('@actions/attest');
const core = require('@actions/core');

async function run() {
    // In order to persist attestations to the repo, this should be a token with
    // repository write permissions.
    const ghToken = core.getInput('gh-token');

    const record = await createStorageRecord(
        artifactOptions: {
            name: 'my-artifact-name',
            digest: { 'sha256': '36ab4667...'},
            version: "v1.0.0"
        },
        packageRegistryOptions: {
            registryUrl: "https://my-fave-pkg-registry.com"
        },
        token: ghToken
    );

    console.log(record);
}

run();
```

这个 `createStorageRecord` 函数支持以下选项:

```typescript
// Artifact details to associate the record with
export type ArtifactOptions = {
  // The name of the artifact
  name: string
  // The digest of the artifact
  digest: string
  // The version of the artifact
  version?: string
  // The status of the artifact
  status?: string
}
// Includes details about the package registry the artifact was published to
export type PackageRegistryOptions = {
  // The URL of the package registry
  registryUrl: string
  // The URL of the artifact in the package registry
  artifactUrl?: string
  // The package registry repository the artifact was published to.
  repo?: string
  // The path of the artifact in the package registry repository.
  path?: string
}
// GitHub token for writing attestations.
token: string
// Optional parameters for the write operation.
// The number of times to retry the request.
retryAttempts?: number
// HTTP headers to include in request to Artifact Metadata API.
headers?: RequestHeaders
```

## Sigstore 实例

当生成签名的证明时, 有两种不同的 Sigstore 用于签发签名证书的示例。 默认, 从公共储存库启动的工作流程将使用Sigstore公益物 并坚持向公众提供证明的签名 [回科尔透明度 日志](https://docs.sigstore.dev/logging/overview/)从 私人/内部存储器将使用 GitHub- 内部 Sigstore 实例 使用GitHub时间戳当局签发的签字时间戳代替 公共透明度记录.

默认的 Sigstore 实例选择可以通过通过一个明示来推翻 “公益”或“github”的数值 `sigstore` 选项 无论是 `attest` 或者说 `attestProvenance`。 。 。 .

## 存储

由 `attest`编号 :`attestProvenance` 将上传到 GH 中 与适当储存库有关的API证明。 证明 仅支持属于公共储存库或储存库的存储 到一个GitHub企业云账户.

为了为私人、非企业储存库提供证明 `skipWrite` 选项应设置为 `true`。 。 。 .

## 常见问题

### @actions/attest 是什么？

证明行动

### 如何安装 @actions/attest？

在项目目录运行 npm install @actions/attest，或使用 pnpm add / yarn add / bun add。

### @actions/attest 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @actions/attest 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @actions/attest 可以商用吗？

@actions/attest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @actions/attest 的下载量有多少？

根据 npm 官方下载统计，@actions/attest 在 2026/10/05 – 2026/11/03 这 30 天内被下载 115,413 次，日均约 3,847 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @actions/attest 还在维护吗？

最新版本 3\.2\.0 发布于 2026/02/27（8 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。