CodePipelineSource

class aws_cdk.pipelines.CodePipelineSource(id)

Bases: Step

Factory for CodePipeline source steps.

This class contains a number of factory methods for the different types of sources that CodePipeline supports.

ExampleMetadata:

infused

Example:

# Access the CommitId of a GitHub source in the synth
source = pipelines.CodePipelineSource.git_hub("owner/repo", "main")

pipeline = pipelines.CodePipeline(scope, "MyPipeline",
    synth=pipelines.ShellStep("Synth",
        input=source,
        commands=[],
        env={
            "COMMIT_ID": source.source_attribute("CommitId")
        }
    )
)
Parameters:

id (str) – Identifier for this step.

Methods

add_step_dependency(step)

Add a dependency on another step.

Parameters:

step (Step) –

Return type:

None

produce_action(stage, *, action_name, artifacts, pipeline, run_order, scope, stack_outputs_map, before_self_mutation=None, code_build_defaults=None, fallback_artifact=None, variables_namespace=None)

Create the desired Action and add it to the pipeline.

Parameters:
  • stage (IStage) –

  • action_name (str) – Name the action should get.

  • artifacts (ArtifactMap) – Helper object to translate FileSets to CodePipeline Artifacts.

  • pipeline (CodePipeline) – The pipeline the action is being generated for.

  • run_order (Union[int, float]) – RunOrder the action should get.

  • scope (Construct) – Scope in which to create constructs.

  • stack_outputs_map (StackOutputsMap) – Helper object to produce variables exported from stack deployments. If your step references outputs from a stack deployment, use this to map the output references to Codepipeline variable names. Note - Codepipeline variables can only be referenced in action configurations.

  • before_self_mutation (Optional[bool]) – Whether or not this action is inserted before self mutation. If it is, the action should take care to reflect some part of its own definition in the pipeline action definition, to trigger a restart after self-mutation (if necessary). Default: false

  • code_build_defaults (Union[CodeBuildOptions, Dict[str, Any], None]) – If this action factory creates a CodeBuild step, default options to inherit. Default: - No CodeBuild project defaults

  • fallback_artifact (Optional[Artifact]) – An input artifact that CodeBuild projects that don’t actually need an input artifact can use. CodeBuild Projects MUST have an input artifact in order to be added to the Pipeline. If the Project doesn’t actually care about its input (it can be anything), it can use the Artifact passed here. Default: - A fallback artifact does not exist

  • variables_namespace (Optional[str]) – If this step is producing outputs, the variables namespace assigned to it. Pass this on to the Action you are creating. Default: - Step doesn’t produce any outputs

Return type:

CodePipelineActionFactoryResult

source_attribute(name)

Return an attribute of the current source revision.

These values can be passed into the environment variables of pipeline steps, so your steps can access information about the source revision.

Pipeline synth step has some source attributes predefined in the environment. If these suffice, you don’t need to use this method for the synth step.

Parameters:

name (str) –

See:

https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-variables.html#reference-variables-list

Return type:

str

Example:

# Access the CommitId of a GitHub source in the synth
source = pipelines.CodePipelineSource.git_hub("owner/repo", "main")

pipeline = pipelines.CodePipeline(scope, "MyPipeline",
    synth=pipelines.ShellStep("Synth",
        input=source,
        commands=[],
        env={
            "COMMIT_ID": source.source_attribute("CommitId")
        }
    )
)
to_string()

Return a string representation of this Step.

Return type:

str

Attributes

consumed_stack_outputs

StackOutputReferences this step consumes.

dependencies

Return the steps this step depends on, based on the FileSets it requires.

dependency_file_sets

The list of FileSets consumed by this Step.

id

Identifier for this step.

is_source

Whether or not this is a Source step.

What it means to be a Source step depends on the engine.

primary_output

The primary FileSet produced by this Step.

Not all steps produce an output FileSet–if they do you can substitute the Step object for the FileSet object.

Static Methods

classmethod code_commit(repository, branch, *, action_name=None, code_build_clone_output=None, event_role=None, trigger=None)

Returns a CodeCommit source.

If you need access to symlinks or the repository history, be sure to set codeBuildCloneOutput.

Parameters:
  • repository (IRepository) – The CodeCommit repository.

  • branch (str) – The branch to use.

  • action_name (Optional[str]) – The action name used for this source in the CodePipeline. Default: - The repository name

  • code_build_clone_output (Optional[bool]) – If this is set, the next CodeBuild job clones the repository (instead of CodePipeline downloading the files). This provides access to repository history, and retains symlinks (symlinks would otherwise be removed by CodePipeline). Note: if this option is true, only CodeBuild jobs can use the output artifact. Default: false

  • event_role (Optional[IRole]) – Role to be used by on commit event rule. Used only when trigger value is CodeCommitTrigger.EVENTS. Default: a new role will be created.

  • trigger (Optional[CodeCommitTrigger]) – How should CodePipeline detect source changes for this Action. Default: CodeCommitTrigger.EVENTS

Return type:

CodePipelineSource

Example:

# repository: codecommit.IRepository

pipelines.CodePipelineSource.code_commit(repository, "main")
classmethod connection(repo_string, branch, *, connection_arn, action_name=None, code_build_clone_output=None, trigger_on_push=None)

Returns a CodeStar connection source.

A CodeStar connection allows AWS CodePipeline to access external resources, such as repositories in GitHub, GitHub Enterprise or BitBucket.

To use this method, you first need to create a CodeStar connection using the AWS console. In the process, you may have to sign in to the external provider – GitHub, for example – to authorize AWS to read and modify your repository. Once you have done this, copy the connection ARN and use it to create the source.

Example:

pipelines.CodePipelineSource.connection("owner/repo", "main",
    connection_arn="arn:aws:codestar-connections:us-east-1:222222222222:connection/7d2469ff-514a-4e4f-9003-5ca4a43cdc41"
)

If you need access to symlinks or the repository history, be sure to set codeBuildCloneOutput.

Parameters:
  • repo_string (str) – A string that encodes owner and repository separated by a slash (e.g. ‘owner/repo’). The provided string must be resolvable at runtime.

  • branch (str) – The branch to use.

  • connection_arn (str) – The ARN of the CodeStar Connection created in the AWS console that has permissions to access this GitHub or BitBucket repository.

  • action_name (Optional[str]) – The action name used for this source in the CodePipeline. Default: - The repository string

  • code_build_clone_output (Optional[bool]) – If this is set, the next CodeBuild job clones the repository (instead of CodePipeline downloading the files). This provides access to repository history, and retains symlinks (symlinks would otherwise be removed by CodePipeline). Note: if this option is true, only CodeBuild jobs can use the output artifact. Default: false

  • trigger_on_push (Optional[bool]) – Controls automatically starting your pipeline when a new commit is made on the configured repository and branch. If unspecified, the default value is true, and the field does not display by default. Default: true

See:

https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html

Return type:

CodePipelineSource

classmethod ecr(repository, *, action_name=None, image_tag=None)

Returns an ECR source.

Parameters:
  • repository (IRepository) – The repository that will be watched for changes.

  • action_name (Optional[str]) – The action name used for this source in the CodePipeline. Default: - The repository name

  • image_tag (Optional[str]) – The image tag that will be checked for changes. Default: latest

Return type:

CodePipelineSource

Example:

# repository: ecr.IRepository

pipelines.CodePipelineSource.ecr(repository,
    image_tag="latest"
)
classmethod git_hub(repo_string, branch, *, action_name=None, authentication=None, trigger=None)

Returns a GitHub source, using OAuth tokens to authenticate with GitHub and a separate webhook to detect changes.

This is no longer the recommended method. Please consider using connection() instead.

Pass in the owner and repository in a single string, like this:

pipelines.CodePipelineSource.git_hub("owner/repo", "main")

Authentication will be done by a secret called github-token in AWS Secrets Manager (unless specified otherwise).

If you rotate the value in the Secret, you must also change at least one property on the Pipeline, to force CloudFormation to re-read the secret.

The token should have these permissions:

  • repo - to read the repository

  • admin:repo_hook - if you plan to use webhooks (true by default)

If you need access to symlinks or the repository history, use a source of type connection instead.

Parameters:
  • repo_string (str) –

  • branch (str) –

  • action_name (Optional[str]) – The action name used for this source in the CodePipeline. Default: - The repository string

  • authentication (Optional[SecretValue]) – A GitHub OAuth token to use for authentication. It is recommended to use a Secrets Manager Secret to obtain the token:: const oauth = cdk.SecretValue.secretsManager(‘my-github-token’); The GitHub Personal Access Token should have these scopes: - repo - to read the repository - admin:repo_hook - if you plan to use webhooks (true by default) Default: - SecretValue.secretsManager(‘github-token’)

  • trigger (Optional[GitHubTrigger]) – How AWS CodePipeline should be triggered. With the default value “WEBHOOK”, a webhook is created in GitHub that triggers the action. With “POLL”, CodePipeline periodically checks the source for changes. With “None”, the action is not triggered through changes in the source. To use WEBHOOK, your GitHub Personal Access Token should have admin:repo_hook scope (in addition to the regular repo scope). Default: GitHubTrigger.WEBHOOK

Return type:

CodePipelineSource

classmethod s3(bucket, object_key, *, action_name=None, role=None, trigger=None)

Returns an S3 source.

Parameters:
  • bucket (IBucket) – The bucket where the source code is located.

  • object_key (str) –

  • action_name (Optional[str]) – The action name used for this source in the CodePipeline. Default: - The bucket name

  • role (Optional[IRole]) – The role that will be assumed by the pipeline prior to executing the S3Source action. Default: - a new role will be generated

  • trigger (Optional[S3Trigger]) – How should CodePipeline detect source changes for this Action. Note that if this is S3Trigger.EVENTS, you need to make sure to include the source Bucket in a CloudTrail Trail, as otherwise the CloudWatch Events will not be emitted. Default: S3Trigger.POLL

Return type:

CodePipelineSource

Example:

# bucket: s3.Bucket

pipelines.CodePipelineSource.s3(bucket, "path/to/file.zip")
classmethod sequence(steps)

Define a sequence of steps to be executed in order.

If you need more fine-grained step ordering, use the addStepDependency() API. For example, if you want secondStep to occur after firstStep, call secondStep.addStepDependency(firstStep).

Parameters:

steps (Sequence[Step]) –

Return type:

List[Step]