CodeStarSourceConnection for Bitbucket Cloud, GitHub, GitHub Enterprise Server, GitLab.com, and GitLab self-managed actions (original) (raw)

Source actions for connections are supported by AWS CodeConnections. CodeConnections allows you to create and manage connections between AWS resources and third-party repositories such as GitHub. Starts a pipeline when a new commit is made on a third-party source code repository. The source action retrieves code changes when a pipeline is manually run or when a webhook event is sent from the source provider.

You can configure actions in your pipeline to use a Git configuration that allows you to start your pipeline with triggers. To configure the pipeline trigger configuration to filter with triggers, see more details in Add trigger with code push or pull request event types.

Note

This feature is not available in the Asia Pacific (Hong Kong), Asia Pacific (Hyderabad), Asia Pacific (Jakarta), Asia Pacific (Melbourne), Asia Pacific (Osaka), Africa (Cape Town), Middle East (Bahrain), Middle East (UAE), Europe (Spain), Europe (Zurich), Israel (Tel Aviv), or AWS GovCloud (US-West) Regions. To reference other available actions, see Product and service integrations with CodePipeline. For considerations with this action in the Europe (Milan) Region, see the note in CodeStarSourceConnection for Bitbucket Cloud, GitHub, GitHub Enterprise Server, GitLab.com, and GitLab self-managed actions.

Connections can associate your AWS resources with the following third-party repositories:

Note

You can create connections to a Bitbucket Cloud repository. Installed Bitbucket provider types, such as Bitbucket Server, are not supported.

If you are using a Bitbucket workspace, you must have administrator access to create the connection.

Note

If your repository is in a GitHub organization, you must be the organization owner to create the connection. If you are using a repository that is not in an organization, you must be the repository owner.

Note

You can create connections to a repository where you have the Owner role in GitLab, and then the connection can be used with the repository with resources such as CodePipeline. For repositories in groups, you do not need to be the group owner.

Note

Each connection supports all of the repositories you have with that provider. You only need to create a new connection for each provider type.

Connections allow your pipeline to detect source changes through the third-party provider's installation app. For example, webhooks are used to subscribe to GitHub event types and can be installed on an organization, a repository, or a GitHub App. Your connection installs a repository webhook on your GitHub App that subscribes to GitHub push type events.

After a code change is detected, you have the following options for passing the code to subsequent actions:

CodePipeline prompts you to add the AWS Connector installation app to your third-party account when you create a connection. You must have already created your third-party provider account and repository before you can connect through theCodeStarSourceConnection action.

Note

To use connections in the Europe (Milan) AWS Region, you must:

  1. Install a Region-specific app
  2. Enable the Region

This Region-specific app supports connections in the Europe (Milan) Region. It is published on the third-party provider site, and it is separate from the existing app supporting connections for other Regions. By installing this app, you authorize third-party providers to share your data with the service for this Region only, and you can revoke the permissions at any time by uninstalling the app.

The service will not process or store your data unless you enable the Region. By enabling this Region, you grant our service permissions to process and store your data.

Even if the Region is not enabled, third-party providers can still share your data with our service if the Region-specific app remains installed, so make sure to uninstall the app once you disable the Region. For more information, see Enabling a Region.

Topics

Action type

Configuration parameters

**ConnectionArn

Required: Yes

The connection ARN that is configured and authenticated for the source provider.

**FullRepositoryId

Required: Yes

The owner and name of the repository where source changes are to be detected.

Example: some-user/my-repo

Important

You must maintain the correct case for theFullRepositoryId value. For example, if your user name is some-user and repo name isMy-Repo, the recommended value ofFullRepositoryId issome-user/My-Repo.

**BranchName

Required: Yes

The name of the branch where source changes are to be detected.

**OutputArtifactFormat

Required: No

Specifies the output artifact format. Can be eitherCODEBUILD_CLONE_REF or CODE_ZIP. If unspecified, the default is CODE_ZIP.

DetectChanges

Required: No

Controls automatically starting your pipeline when a new commit is made on the configured repository and branch. If unspecified, the default value istrue, and the field does not display by default. Valid values for this parameter:

Input artifacts

Output artifacts

Output variables

When configured, this action produces variables that can be referenced by the action configuration of a downstream action in the pipeline. This action produces variables which can be viewed as output variables, even if the action doesn't have a namespace. You configure an action with a namespace to make those variables available to the configuration of downstream actions.

For more information, see Variables reference.

AuthorDate

The date when the commit was authored, in timestamp format.

BranchName

The name of the branch for the repository where the source change was made.

CommitId

The commit ID that triggered the pipeline execution.

CommitMessage

The description message, if any, associated with the commit that triggered the pipeline execution.

ConnectionArn

The connection ARN that is configured and authenticated for the source provider.

FullRepositoryName

The name of the repository where the commit that triggered the pipeline was made.

Service role permissions: CodeConnections action

For CodeConnections, the following permission is required to create pipelines with a source that uses a connection, such as Bitbucket Cloud.

{
    "Effect": "Allow",
    "Action": [
        "codeconnections:UseConnection"
    ],
    "Resource": "resource_ARN"
},

For more information about the IAM permissions for connections, see Connections permissions reference.

Action declaration

In the following example, the output artifact is set to the default ZIP format ofCODE_ZIP for the connection with ARNarn:aws:codestar-connections:region:`account-id`:connection/`connection-id`.

YAML

Name: Source
Actions:
  - InputArtifacts: []
    ActionTypeId:
      Version: '1'
      Owner: AWS
      Category: Source
      Provider: CodeStarSourceConnection
    OutputArtifacts:
      - Name: SourceArtifact
    RunOrder: 1
    Configuration:
      ConnectionArn: "arn:aws:codestar-connections:region:account-id:connection/connection-id"
      FullRepositoryId: "some-user/my-repo"
      BranchName: "main"
      OutputArtifactFormat: "CODE_ZIP"
    Name: ApplicationSource

JSON

{
    "Name": "Source",
    "Actions": [
        {
            "InputArtifacts": [],
            "ActionTypeId": {
                "Version": "1",
                "Owner": "AWS",
                "Category": "Source",
                "Provider": "CodeStarSourceConnection"
            },
            "OutputArtifacts": [
                {
                    "Name": "SourceArtifact"
                }
            ],
            "RunOrder": 1,
            "Configuration": {
                "ConnectionArn": "arn:aws:codestar-connections:region:account-id:connection/connection-id",
                "FullRepositoryId": "some-user/my-repo",
                "BranchName": "main",
                "OutputArtifactFormat": "CODE_ZIP"
            },
            "Name": "ApplicationSource"
        }
    ]
},

Installing the installation app and creating a connection

The first time you use the console to add a new connection to a third-party repository, you must authorize CodePipeline access to your repositories. You choose or create an installation app that helps you connect to the account where you have created your third-party code repository.

When you use the AWS CLI or an AWS CloudFormation template, you must provide the connection ARN of a connection that has already gone through the installation handshake. Otherwise, the pipeline is not triggered.

Note

For a CodeStarSourceConnection source action, you do not have to set up a webhook or default to polling. The connections action manages your source change detection for you.

See also

The following related resources can help you as you work with this action.