Troubleshooting connections

The following information might help you troubleshoot common issues with connections to resources in AWS CodeBuild, AWS CodeDeploy, and AWS CodePipeline.

I cannot create connections

You might not have permissions to create a connection. For more information, see Permissions and examples for AWS CodeConnections.

I get a permissions error when I try to create or complete a connection

The following error message might be returned when you try to create or view a connection in the CodePipeline console.

User: username is not authorized to perform: permission on resource: connection-ARN

If this message appears, make sure that you have sufficient permissions.

The permissions to create and view connections in the AWS Command Line Interface (AWS CLI) or the AWS Management Console are only part of the permissions that you need to create and complete connections on the console. The permissions required to simply view, edit, or create a connection and then complete the pending connection should be scoped down for users who only need to perform certain tasks. For more information, see Permissions and examples for AWS CodeConnections.

I get a permissions error when I try to use a connection

One or both of the following error messages might be returned if you try to use a connection in the CodePipeline console, even though you have the permissions to list, get, and create permissions.

You have failed to authenticate your account.

User: username is not authorized to perform: codestar-connections:UseConnection on resource: connection-ARN

If this occurs, make sure that you have sufficient permissions.

Make sure you have the permissions to use a connection, including listing the available repositories in the provider location. For more information, see Permissions and examples for AWS CodeConnections.

Connection is not in available state or is no longer pending

If the console displays a message that a connection is not in an available state, choose Complete connection.

If you choose to complete the connection and a message appears that the connection is not in a pending state, you can cancel the request because the connection is already in an available state.

Add GitClone permissions for connections

When you use an AWS CodeStar connection in a source action and a CodeBuild action, there are two ways the input artifact can be passed to the build:

To add permissions to your CodeBuild service role policy, you create a customer managed policy that you attach to your CodeBuild service role. The following steps create a policy where the UseConnection permission is specified in the action field, and the connection Amazon Resource Name (ARN) is specified in the Resource field.

Host is not in available state

If the console displays a message that a host is not in an Available state, choose Set up host.

The first step for host creation results in the created host now in a Pending state. To move the host to an Available state, you must choose to set up the host in the console. For more information, see Set up a pending host.

Troubleshooting a host with connection errors

Connections and hosts can move into the error state if the underlying GitHub app is deleted or modified. Hosts and connections in the error state cannot be recovered and the host must be recreated.

If the console or CLI returns a host or a connection related to a host with an Error state, you might need to perform the following step:

I’m unable to create a connection for my host

To create a connection or host, the following conditions are required.

Troubleshooting VPC configuration for your host

When you create a host resource, you must provide network connection or VPC information for the infrastructure where your GitHub Enterprise Server instance is installed. For troubleshooting your VPC or subnet configuration for your host, use the example VPC information shown here as a reference.

For this example, you would use the following process to configure the VPC and server where your GitHub Enterprise Server instance will be installed:

The following image shows an EC2 instance launched using the GitHub Enterprise AMI.

When you use a VPC for a GitHub Enterprise Server connection, you must provide the following for your infrastructure when you set up your host:

For more information about working with VPCs and subnets, see VPC and Subnet Sizing for IPv4 in the Amazon VPC User Guide.

I’m unable to get a host in pending state

If your host enters the VPC_CONFIG_FAILED_INITIALIZATION state, this is likely because of an issue with the VPC, subnets, or security groups that you have selected for your host.

I’m unable to get a host in available state

If you are unable to complete the CodeConnections app setup for your host, it may be because of an issue with your VPC configurations or your GitHub Enterprise Server instance.

My connection/host was working and has stopped working now

If a connection/host was working before and is not working now, it could be due to a configuration change in your VPC or the GitHub app has been modified. Check the following:

I’m unable to delete my network interfaces

If you are unable to detect your network interfaces, check the following:

Troubleshooting webhook VPC endpoints (PrivateLink) for GitHub Enterprise Server connections

When you create a host with VPC configuration, the webhook VPC endpoint is created for you.

When you create a connection to an installed provider type, and you have specified that your server is configured within a VPC, then AWS CodeConnections creates your host, and the VPC endpoint (PrivateLink) for webhooks is created for you. This enables the host to send event data via webhooks to your integrated AWS services over the Amazon network. For more information, see AWS CodeConnections and interface VPC endpoints (AWS PrivateLink).

I’m unable to delete my webhook VPC endpoints

AWS CodeConnections manages the lifecycle of the webhook VPC endpoints for your host. If you want to delete the endpoint, you must do this by deleting the corresponding host resource.

Troubleshooting for a host created before November 24, 2020

As of November 24, 2020, when AWS CodeConnections sets up your host, an additional VPC endpoint (PrivateLink) support is set up for you. For hosts created before this update, use this troubleshooting section.

For more information, see AWS CodeConnections and interface VPC endpoints (AWS PrivateLink).

I have a host that was created before November 24, 2020 and I want to use VPC endpoints (PrivateLink) for webhooks

When you set up your host for GitHub Enterprise Server, the webhook endpoint is created for you. Connections now use VPC PrivateLink webhook endpoints. If you created your host before November 24, 2020, and you want to use VPC PrivateLink webhook endpoints, you must first delete your host and then create a new host.

I’m unable to get a host in available state (VPC error)

If your host was created before November 24, 2020, and you are unable to complete the CodeConnections app setup for your host, it may be because of an issue with your VPC configurations or your GitHub Enterprise Server instance.

Your VPC will need a NAT Gateway (or outbound internet access) so that your GitHub Enterprise Server instance can send egress network traffic for GitHub webhooks.

Unable to create the connection for a GitHub repository

Problem:

Because a connection to a GitHub repository uses the AWS Connector for GitHub, you need organization owner permissions or admin permissions to the repository to create the connection.

Possible fixes: For information about permission levels for a GitHub repository, see https://docs.github.com/en/free-pro-team@latest/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.

Edit your GitHub Enterprise Server connection app permissions

If you installed the app for GitHub Enterprise Server on or before December 23, 2020, you might need to give the app Read-only access to members of the organization. If you are the GitHub app owner, follow these steps to edit the permissions for the app that was installed when your host was created.

Connections error when connecting to GitHub: "A problem occurred, make sure cookies are enabled in your browser" or "An organization owner must install the GitHub app"

Problem:

To create the connection for a GitHub repository, you must be the GitHub organization owner. For repositories that are not under an organization, you must be the repository owner. When a connection is created by someone other than the organization owner, a request is created for the organization owner, and one of the following errors display:

A problem occurred, make sure cookies are enabled in your browser

OR

An organization owner must install the GitHub app

Possible fixes: For repositories in a GitHub organization, the organization owner must create the connection to the GitHub repository. For repositories that are not under an organization, you must be the repository owner.

Connections service prefix in resources might need to be updated for IAM policies

On March 29, 2024, the service was renamed from AWS CodeStar Connections to AWS CodeConnections. Beginning July 1, 2024, the console creates connections with codeconnections in the resource ARN. Resources with both service prefixes will continue to display in the console. The service prefix for resources created using the console is codeconnections. New SDK/CLI resources are created with codeconnections in the resource ARN. Resources created will automatically have the new service prefix.

The following are the resources that are created in AWS CodeConnections:

Problem:

Resources that have been created with codestar-connections in the ARN will not automatically be renamed to the new service prefix in the resource ARN. Creating a new resource will create a resource that has the connections service prefix. However, IAM policies with the codestar-connections service prefix will not work for resources with the new service prefix.

Possible fixes: To avoid access or permissions issues for the resources, complete the following actions:

Update the actions, resources, and conditions in the policy as appropriate. In the following example, the Resource field has been updated for both service prefixes.

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Action": [
            "codeconnections:UseConnection"
        ],
        "Resource": [
            "arn:aws:codestar-connections:*:*:connection/*",
            "arn:aws:codeconnections:*:*:connection/*"
        ]
    }
}

Permissions error due to service prefix in resources created using the console

Currently, connections resources that are created using the console will only have the codestar-connections service prefix. For resources created using the console, policy statement actions must include codestar-connections as the service prefix.

Problem:

When creating a connections resource using the console, the codestar-connections service prefix must be used in the policy. When using a policy with the codeconnections service prefix in the policy, connections resources created using the console receive the following error message:

User: user_ARN is not authorized to perform: codestar-connections:action on resource: resource_ARN because no identity-based policy allows the codestar-connections:action action

Possible fixes: For resources created using the console, policy statement actions must include codestar-connections as the service prefix, as shown in the policy example in Example: A policy for creating AWS CodeConnections with the console.

Connection and host setup for installed providers supporting organizations

For installed providers that support organizations, such as GitHub Organizations, you don’t pass an available host. You create a new host for each connection in your organization and be sure to enter the same information in the following network fields:

See the related steps to create a GHES connection or a GitLab self-managed connection.

I want to increase my limits for connections

You can request a limit increase for certain limits in CodeConnections. For more information, see Quotas for connections.