# @aws-cdk/aws-codepipeline 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-codepipeline/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:14:26.569Z
中文译文更新时间：2026-11-07T11:57:45.015Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-codepipeline
原文对照：https://npmcn.com/package/%40aws-cdk/aws-codepipeline/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

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

- 包体积（解压后）：1.3 MB，32 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：7 个
- peer 依赖：@aws-cdk/aws-codestarnotifications 1\.204\.0，@aws-cdk/aws-events 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-kms 1\.204\.0，@aws-cdk/aws-s3 1\.204\.0，@aws-cdk/core 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:31:42.862Z
- 最新版本发布：2023-06-19T21:05:54.079Z
- 近 30 天下载量：104987（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

更好的接口到 AWS 代码管道

## 安装

```sh
npm install @aws-cdk/aws-codepipeline
```

也可以使用：`pnpm add @aws-cdk/aws-codepipeline`、`yarn add @aws-cdk/aws-codepipeline`、`bun add @aws-cdk/aws-codepipeline`

## README

# AWS 代码平线构造库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

## 管道

要构造空管道 :

```ts
// Construct an empty Pipeline
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline');
```

为了给管道一个人能读取的好名字:

```ts
// Give the Pipeline a nice, human-readable name
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  pipelineName: 'MyPipeline',
});
```

注意在默认配置中 `Pipeline` 构造创建 aWS 密钥管理服务( AWS KMS) 客户主密钥( CMK) 供您使用 加密文物桶中的文物,费用为: **1美元/个月**。此默认配置对于允许交叉账户是必要的 行动.

如果您不打算进行交叉账户部署, 可以禁用 通过传递创建客户主密钥 `crossAccountKeys: false` 当定义管道时 :

```ts
// Don't create Customer Master Keys
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  crossAccountKeys: false,
});
```

如果您想要为生成的 KMS 密钥启用密钥旋转, 你可以通过路过来配置它 `enableKeyRotation: true` 当创建管道时. 注意关键轮换将产生额外费用 **1美元/个月**。 。 。 .

```ts
// Enable key rotation for the generated KMS key
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  // ...
  enableKeyRotation: true,
});
```

## 阶段

您可以在创建管道时提供阶段 :

```ts
// Provide a Stage when creating a pipeline
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  stages: [
    {
      stageName: 'Source',
      actions: [
        // see below...
      ],
    },
  ],
});
```

或将一个阶段附加到已有管道中 :

```ts
// Append a Stage to an existing Pipeline
declare const pipeline: codepipeline.Pipeline;
const sourceStage = pipeline.addStage({
  stageName: 'Source',
  actions: [ // optional property
    // see below...
  ],
});
```

您可以在管道的任意点插入新阶段 :

```ts
// Insert a new Stage at an arbitrary point
declare const pipeline: codepipeline.Pipeline;
declare const anotherStage: codepipeline.IStage;
declare const yetAnotherStage: codepipeline.IStage;

const someStage = pipeline.addStage({
  stageName: 'SomeStage',
  placement: {
    // note: you can only specify one of the below properties
    rightBefore: anotherStage,
    justAfter: yetAnotherStage,
  }
});
```

您可以禁用向阶段的过渡 :

```ts
// Disable transition to a stage
declare const pipeline: codepipeline.Pipeline;

const someStage = pipeline.addStage({
  stageName: 'SomeStage',
  transitionToEnabled: false,
  transitionDisabledReason: 'Manual transition only', // optional reason
})
```

如果你不想让每一次处决 都进入 这个阶段自动。 之后过渡可以"手动"后被启用.

## 行动

动作在一个单独的包, `@aws-cdk/aws-codepipeline-actions`。 。 。 .

要在阶段中添加动作,您可以在创建阶段时提供它, 输入 `actions` 财产, 或者你可以使用 `IStage.addAction()` 改变现有阶段的方法:

```ts
// Use the `IStage.addAction()` method to mutate an existing Stage.
declare const sourceStage: codepipeline.IStage;
declare const someAction: codepipeline.Action;
sourceStage.addAction(someAction);
```

## 自定义行动注册

为了让自己的自定义代码Pipeline Action需要注册动作提供者. 看着 `JenkinsProvider` 内 `@aws-cdk/aws-codepipeline-actions` 以实施为例.

```ts
// Make a custom CodePipeline Action
new codepipeline.CustomActionRegistration(this, 'GenericGitSourceProviderResource', {
  category: codepipeline.ActionCategory.SOURCE,
  artifactBounds: { minInputs: 0, maxInputs: 0, minOutputs: 1, maxOutputs: 1 },
  provider: 'GenericGitSource',
  version: '1',
  entityUrl: 'https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html',
  executionUrl: 'https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html',
  actionProperties: [
    {
      name: 'Branch',
      required: true,
      key: false,
      secret: false,
      queryable: false,
      description: 'Git branch to pull',
      type: 'String',
    },
    {
      name: 'GitUrl',
      required: true,
      key: false,
      secret: false,
      queryable: false,
      description: 'SSH git clone URL',
      type: 'String',
    },
  ],
});
```

## 交叉账户代码

> 跨账户管道行动要求管道具备 _没有_ 已经 创建于 `crossAccountKeys: false`。 。 。 .

大多数管道动作接受 AWS 资源对象运行. 例如:

-   `S3DeployAction` 接受一个 `s3.IBucket`。 。 。 .
-   `CodeBuildAction` 接受一个 `codebuild.IProject`。 。 。 .
-   包括:.

这些资源可以是新定义的(`new s3.Bucket(...)`)或导入 (单位:千美元)`s3.Bucket.fromBucketAttributes(...)`(b) 确定应提供的资源 改为:.

这些资源可能与管道本身不同。 对于 例如,以下行动将部署在从一个 不同账户 :

```ts
// Deploy an imported S3 bucket from a different account
declare const stage: codepipeline.IStage;
declare const input: codepipeline.Artifact;
stage.addAction(new codepipeline_actions.S3DeployAction({
  bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
    account: '123456789012',
    // ...
  }),
  input: input,
  actionName: 's3-deploy-action',
  // ...
}));
```

不接受资源对象的动作接受明示 `account` 参数 :

```ts
// Actions that don't accept a resource objet accept an explicit `account` parameter
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  account: '123456789012',
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
}));
```

这个 `Pipeline` 构造自动定义 **IAM 作用** 为你在 目标账户,管道将假设 执行这一行动。 这个 作用将在 **支持堆栈** 名称 `<PipelineStackName>-support-<account>`,将自动部署 在包含管道的堆栈之前.

如果您不想使用生成的角色,也可以明确通过一个 `role` 当创建动作时。 在这样的情况下,行动将在 该角色属于:

```ts
// Explicitly pass in a `role` when creating an action.
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
  role: iam.Role.fromRoleArn(this, 'ActionRole', '...'),
}));
```

## 跨区域代码

类似于您如何设置交叉账户动作, AWS 资源对象为您 转到动作也可以是不同的 _区域_。例如 以下动作部署在从不同区域进口的S3桶上:

```ts
// Deploy to an imported S3 bucket from a different Region.
declare const stage: codepipeline.IStage;
declare const input: codepipeline.Artifact;
stage.addAction(new codepipeline_actions.S3DeployAction({
  bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
    region: 'us-west-1',
    // ...
  }),
  input: input,
  actionName: 's3-deploy-action',
  // ...
}));
```

不使用 AWS 资源的动作会接受一个明确的 `region` 参数 :

```ts
// Actions that don't take an AWS resource will accept an explicit `region` parameter.
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
  region: 'us-west-1',
}));
```

这个 `Pipeline` 构造自动定义 a **复制桶** 页:1 在目标区域, 管道将复制 文物到和 从. 此桶将在 **支持堆栈** 名称 `<PipelineStackName>-support-<region>`,将自动部署 在包含管道的堆栈之前.

如果你不想使用这些支持堆栈, 并且已经装有桶 作为复制桶的地方, 您可以在管道定义中提供这些 使用时间 `crossRegionReplicationBuckets` 参数。 示例

```ts
// Supply replication buckets for the Pipeline instead of using the generated support stack
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  // ...

  crossRegionReplicationBuckets: {
    // note that a physical name of the replication Bucket must be known at synthesis time
    'us-west-1': s3.Bucket.fromBucketAttributes(this, 'UsWest1ReplicationBucket', {
      bucketName: 'my-us-west-1-replication-bucket',
      // optional KMS key
      encryptionKey: kms.Key.fromKeyArn(this, 'UsWest1ReplicationKey',
        'arn:aws:kms:us-west-1:123456789012:key/1234-5678-9012'
      ),
    }),
  },
});
```

见 [这里的 AWS 文件](https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-cross-region.html) 欲了解更多跨区域代码.

### 创建加密复制桶

如果你通过一个复制桶 在不同的堆叠, 像这样:

```ts
// Passing a replication bucket created in a different stack.
const app = new App();
const replicationStack = new Stack(app, 'ReplicationStack', {
  env: {
    region: 'us-west-1',
  },
});
const key = new kms.Key(replicationStack, 'ReplicationKey');
const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
  // like was said above - replication buckets need a set physical name
  bucketName: PhysicalName.GENERATE_IF_NEEDED,
  encryptionKey: key, // does not work!
});

// later...
new codepipeline.Pipeline(replicationStack, 'Pipeline', {
  crossRegionReplicationBuckets: {
    'us-west-1': replicationBucket,
  },
});
```

当试图加密时 (并注意如果任何跨区域行动也恰好是交叉账户, 桶头 _必须_ 加密 - 否则管道在运行时会失效 ), 无法直接使用密钥 - KMS 密钥没有物理名称, 所以你不能在环境中参考它们.

在这种情况下,在创建水桶时需要使用别名来代替密钥:

```ts
// Passing an encrypted replication bucket created in a different stack.
const app = new App();
const replicationStack = new Stack(app, 'ReplicationStack', {
  env: {
    region: 'us-west-1',
  },
});
const key = new kms.Key(replicationStack, 'ReplicationKey');
const alias = new kms.Alias(replicationStack, 'ReplicationAlias', {
  // aliasName is required
  aliasName: PhysicalName.GENERATE_IF_NEEDED,
  targetKey: key,
});
const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
  bucketName: PhysicalName.GENERATE_IF_NEEDED,
  encryptionKey: alias,
});
```

## 变量

库支持CodePipeline可变特性. 发出变量的每个动作类都有单独的变量接口, 作为诉讼案件财产使用 `variables`。 。 。 . 将动作舱立即分配到本地的变量上; 如果您想要在不同的动作配置中使用变量, 您访问从 `variables`, (中文(简体) ), 表示单个变量. 示例

```ts
// MyAction is some action type that produces variables, like EcrSourceAction
const myAction = new MyAction({
  // ...
  actionName: 'myAction',
});
new OtherAction({
  // ...
  config: myAction.variables.myVariable,
  actionName: 'otherAction',
});
```

将使用的命名空间名称将由管道构造自动生成, 基于舞台和行动名称; 创建动作实例时, 您可以通过自定义名称 :

```ts
// MyAction is some action type that produces variables, like EcrSourceAction
const myAction = new MyAction({
  // ...
  variablesNamespace: 'MyNamespace',
  actionName: 'myAction',
});
```

还存在全球变量, 与任何行动无关; 它们是通过 `GlobalVariables` 类 :

```ts
// OtherAction is some action type that produces variables, like EcrSourceAction
new OtherAction({
  // ...
  config: codepipeline.GlobalVariables.executionId,
  actionName: 'otherAction',
});
```

检查文件 `@aws-cdk/aws-codepipeline-actions` 详细介绍如何使用每个动作类的变量.

见 [代码平线文档](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-variables.html) 关于如何使用变量特性的更详细信息.

## 活动

### 利用管道作为事件目标

管道可以作为云表事件规则的目标:

```ts
// A pipeline being used as a target for a CloudWatch event rule.
import * as targets from '@aws-cdk/aws-events-targets';
import * as events from '@aws-cdk/aws-events';

// kick off the pipeline every day
const rule = new events.Rule(this, 'Daily', {
  schedule: events.Schedule.rate(Duration.days(1)),
});

declare const pipeline: codepipeline.Pipeline;
rule.addTarget(new targets.CodePipeline(pipeline));
```

当管道被用作事件目标时 “编码管:启动PipelineExecution”被授予AWS 云表事件服务.

### 事件来源

管道释放出"云表"事件. 定义事件规则 管道、阶段或行动,使用 `onXxx` 有关方法 构造 :

```ts
// Define event rules for events emitted by the pipeline
import * as events from '@aws-cdk/aws-events';

declare const myPipeline: codepipeline.Pipeline;
declare const myStage: codepipeline.IStage;
declare const myAction: codepipeline.Action;
declare const target: events.IRuleTarget;
myPipeline.onStateChange('MyPipelineStateChange', { target: target } );
myStage.onStateChange('MyStageStateChange', target);
myAction.onStateChange('MyActionStateChange', target);
```

## 代码星通知

要定义管道的代码星通知规则,请使用其中之一 `notifyOnXxx()` 方法。 。 . 它们与 `onXxx()` 云表事件的方法:

```ts
// Define CodeStar Notification rules for Pipelines
import * as chatbot from '@aws-cdk/aws-chatbot';
const target = new chatbot.SlackChannelConfiguration(this, 'MySlackChannel', {
  slackChannelConfigurationName: 'YOUR_CHANNEL_NAME',
  slackWorkspaceId: 'YOUR_SLACK_WORKSPACE_ID',
  slackChannelId: 'YOUR_SLACK_CHANNEL_ID',
});

declare const pipeline: codepipeline.Pipeline;
const rule = pipeline.notifyOnExecutionStateChange('NotifyOnExecutionStateChange', target);
```

## 常见问题

### @aws-cdk/aws-codepipeline 是什么？

更好的接口到 AWS 代码管道注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-codepipeline？

在项目目录运行 npm install @aws-cdk/aws-codepipeline，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-codestarnotifications（1\.204\.0）、@aws-cdk/aws-events（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-kms（1\.204\.0）、@aws-cdk/aws-s3（1\.204\.0）、@aws-cdk/core（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-codepipeline 支持 TypeScript 吗？

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

### @aws-cdk/aws-codepipeline 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-codepipeline 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-codepipeline 可以商用吗？

@aws-cdk/aws-codepipeline 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-codepipeline 的下载量有多少？

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

### @aws-cdk/aws-codepipeline 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。