What are connections? - Developer Tools console

What are connections?

You can use the connections feature in the Developer Tools console to connect AWS resources such as AWS CodePipeline to external code repositories. This feature has its own API, the AWS CodeStar Connections API reference. Each connection is a resource that you can give to AWS services to connect to a third-party repository, such as BitBucket. For example, you can add the connection in CodePipeline so that it triggers your pipeline when a code change is made to your third-party code repository. Each connection is named and associated with a unique Amazon Resource Name (ARN) that is used to reference the connection.

What can I do with connections?

You can use connections to integrate third-party provider resources with your AWS resources in developer tools, including:

  • Connect to a third-party provider, such as Bitbucket, and use the third-party connection as a source integration with your AWS resources, such as CodePipeline.

  • Uniformly manage access to your connection across your resources in CodeBuild build projects, CodeDeploy applications, and pipelines in CodePipeline for your third-party provider.

  • Use a connection ARN in your stack templates for CodeBuild build projects, CodeDeploy applications, and pipelines in CodePipeline, without the need to reference stored secrets or parameters.

How do connections work?

Before you can create a connection, you must first install, or provide access to, the AWS authentication app on your third-party account. After a connection is installed, it can be updated to use this installation. When you create a connection, you provide access to the AWS resource in your third-party account. This allows the connection to access content, such as source repositories, in the third-party account, on behalf of your AWS resources. You can then share that connection with other AWS services to provide secure OAuth connections between the resources.

If you want to create a connection to an installed provider type, such as GitHub Enterprise Server, you first create a host resource using the AWS Management Console.


        Diagram showing the connections between AWS resources and a third-party repository
          using connection ARNs.

Connections are owned by the AWS account that creates them. Connections are identified by an ARN containing a connection ID. The connection ID is a UUID that cannot be changed or remapped. Deleting and re-establishing a connection results in a new connection ID, and therefore a new connection ARN. This means that connection ARNs are never reused.

A newly created connection is in a Pending state. A third-party handshake (OAuth flow) process is required to complete setup of the connection and for it to move from Pending to an Available state. After this is complete, a connection is Available and can be used with AWS services, such as CodePipeline.

A newly created host is in a Pending state. A third-party registration process is required to complete setup of the host and for it to move from Pending to an Available state. After this is complete, a host is Available and can be used for connections to installed provider types.

Global resources in AWS CodeStar Connections

Connections are global resources, meaning that the resource is replicated across all AWS Regions.

Although the connection ARN format reflects the Region name where it was created, the resource is not constrained to any Region. The Region where the connection resource was created is the Region where connection resource data updates are controlled. Examples of API operations that control updates to connection resource data include creating a connection, updating an installation, deleting a connection, or tagging a connection.

Host resources for connections are not globally available resources. You use host resources only in the Region where they were created.

  • You only have to create a connection once, and then you can use it in any AWS Region.

  • If the Region where the connection was created is having issues, this impacts APIs that control connection resource data, but you can still successfully use the connection in every other Region.

  • When you list connection resources in the console or CLI, the list shows all connection resources associated with your account across all Regions.

  • When you list host resources in the console or CLI, the list shows host resources associated with your account in the selected Region only.

  • When a connection with an associated host resource is listed or viewed with the CLI, the output returns the host ARN regardless of the configured CLI Region.

Workflow to create or update connections

When you create a connection, you also create or use an existing installation for the auth handshake with the third-party provider.

Connections can have the following states:

  • Pending - A pending connection is a connection that must be completed (moved to available) before it can be used.

  • Available - You can use or pass an available connection to other resources and users in your account.

  • Error - A connection that has an error state is retried automatically. It cannot be used until it is available.

Workflow: Creating or updating a connection with the CLI, SDK, or AWS CloudFormation

You use the CreateConnection API to create a connection using the AWS Command Line Interface (AWS CLI), SDK, or AWS CloudFormation. After it is created, the connection is in a pending state. You complete the process by using the console Set up pending connection option. The console prompts you to create an installation or use an existing installation for the connection. You then use the console to complete the handshake and move the connection to an available state by choosing Complete connection on the console.

Workflow: Creating or updating a connection with the console

If you are creating a connection to an installed provider type, such as GitHub Enterprise Server, you first create a host. If you are connecting to a cloud provider type, such as Bitbucket, you skip creating the host and continue to creating a connection.

To create or update a connection using the console, you use the CodePipeline edit action page on the console to choose your third-party provider. The console prompts you to create an installation or use an existing installation for the connection, and then use the console to create the connection. The console completes the handshake and moves the connection from pending to an available state automatically.


          Diagram showing the workflow of creating a connection to third-party
            provider.

How do I get started with connections?

To get started, here are some useful topics to review: