Troubleshooting connections - Developer Tools console

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 CodeStar Connections.

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 CodeStar Connections.

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 CodeStar Connections.

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:

  • The default: The source action produces a zip file that contains the code that CodeBuild downloads.

  • Git clone: The source code can be directly downloaded to the build environment.

    The Git clone mode allows you to interact with the source code as a working Git repository. To use this mode, you must grant your CodeBuild environment permissions to use the connection.

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.

To use the console to add the UseConnection permissions

  1. To find the connection ARN for your pipeline, open your pipeline and choose the (i) icon on your source action. The Configuration pane opens, and the connection ARN appears next to ConnectionArn. You add the connection ARN to your CodeBuild service role policy.

  2. To find your CodeBuild service role, open the build project used in your pipeline and navigate to the Build details tab.

  3. In the Environment section, choose the Service role link. This opens the AWS Identity and Access Management (IAM) console, where you can add a new policy that grants access to your connection.

  4. In the IAM console, choose Attach policies, and then choose Create policy.

    Use the following sample policy template. Add your connection ARN in the Resource field, as shown in this example.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "codestar-connections:UseConnection", "Resource": "insert connection ARN here" } ] }

    On the JSON tab, paste your policy.

  5. Choose Review policy. Enter a name for the policy (for example, connection-permissions), and then choose Create policy.

  6. Return to the service role Attach Permissions page, refresh the policy list, and select the policy you just created. Choose Attach policies.

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.

Note

You cannot use the AWS CLI to 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.

  • Actions such as changing the app pem key, changing the app name (after initial creation) will cause the host and all associated connections to go into the error state.

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:

  • Delete and recreate the host resource and then reinstall the host registration app. For more information, see Create a host.

I’m unable to create a connection for my host

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

  • Your host must be in the AVAILABLE state. For more information, see

  • Connections must be created in the same Region as the host.

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.


        Console screenshot showing instance description

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:

  • VPC ID: The VPC for the server where your GitHub Enterprise Server instance is installed or a VPC which has access to your installed GitHub Enterprise Server instance through VPN or Direct Connect.

  • Subnet ID or IDs: The subnet for the server where your GitHub Enterprise Server instance is installed or a subnet with access to your installed GitHub Enterprise Server instance through VPN or Direct Connect.

  • Security group or groups: The security group for the server where your GitHub Enterprise Server instance is installed or a security group with access to your installed GitHub Enterprise Server instance through VPN or Direct Connect.

  • Endpoint: Have your server endpoint ready and continue to the next step.

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.

  • The VPC, subnets, and security groups must all belong to the account creating the host.

  • The subnets and security groups must belong to the selected VPC.

  • Each provided subnet must be in different Availability Zones.

  • The user creating the host must have the following IAM permissions:

    ec2:CreateNetworkInterface ec2:CreateTags ec2:DescribeDhcpOptions ec2:DescribeDhcpOptions ec2:DescribeNetworkInterfaces ec2:DescribeSubnets ec2:DeleteNetworkInterface ec2:DescribeVpcs

I’m unable to get a host in available state

If you are unable to complete the AWS CodeStar Connections 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.

    • The security groups used during host creation will need outbound rules that allow the network interface to connect to your GitHub Enterprise Server instance

    • The security groups attached to your GitHub Enterprise Server instance (not part of the host setup) will require inbound access from the network interfaces created by AWS CodeStar Connections.

  • If you are not using a public certificate authority, you will need to provide a TLS certificate to your host that is used by your GitHub Enterprise Instance. The TLS Certificate value should be the public key of the certificate.

  • You need to be an administrator of the GitHub Enterprise Server instance in order to create GitHub apps.

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:

  • The security group attached to the host resource you created for your connection has now changed or no longer has access to the GitHub Enterprise Server. AWS CodeStar Connections requires a security group which has connectivity to the GitHub Enterprise Server instance.

  • DNS Server IP has recently changed. You can verify this by checking the DHCP options attached to the VPC specified in the host resource you created for your connection. Note that if you’ve recently moved from AmazonProvidedDNS to custom DNS Server or started using a new custom DNS Server, the host/connection would stop working. In order to fix this, delete your existing host and re-create it, which would store the latest DNS settings in our database.

  • The network ACLs settings have changed and are no longer allowing HTTP connections to the subnet where your GitHub Enterprise Server infrastructure is located.

  • Any configurations of the AWS CodeStar Connections app on your GitHub Enterprise Server have changed. Modifications to any of the configurations, such as URLs or app secrets, can break the connectivity between your installed GitHub Enterprise Server instance and AWS CodeStar Connections.

I’m unable to delete my network interfaces

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

  • The Network Interfaces created by AWS CodeStar Connections can only be deleted by deleting the host. They cannot be deleted manually by the user.

  • You must have the following permissions:

    ec2:DescribeNetworkInterfaces ec2:DeleteNetworkInterface

I want to increase my limits for connections

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