Create a connection to GitHub Enterprise Server (console) - Developer Tools console

Create a connection to GitHub Enterprise Server (console)

To create a GitHub Enterprise Server connection, you provide information for where your GitHub Enterprise Server is installed and authorize the connection creation with your GitHub Enterprise credentials.

Prerequisites: Network or Amazon VPC configuration for your connection

If your infrastructure is configured with a network connection, you can skip this section and continue to Create your GitHub Enterprise Server connection (console).

If your GitHub Enterprise Server is only accessible in a VPC, follow these VPC requirements before you continue to Create your GitHub Enterprise Server connection (console).

Important

AWS CodeStar Connections does not support GitHub Enterprise Server version 2.22.0 due to a known issue in the release. To connect, upgrade to version 2.22.1 or the latest available version.

VPC requirements

The following are general VPC requirements, depending on the VPC you have set up for your installation.

  • You can configure a public VPC with public and private subnets. You can use the default VPC for your AWS account if you do not have preferred CIDR blocks or subnets.

  • If you have a private VPC configured, and you have configured your GitHub Enterprise Server instance to perform TLS validation using a non-public certificate authority, you need to provide the TLS certificate for your host resource.

  • When AWS CodeStar Connections creates your host, the VPC endpoint (PrivateLink) for webhooks is created for you. For more information, see AWS CodeStar Connections and interface VPC endpoints (AWS PrivateLink).

  • Security group configuration:

    • The security groups used during host creation need inbound and 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) need inbound and outbound access from the network interfaces created by connections.

  • Your VPC subnets must reside in different Availability Zones in your Region. Availability Zones are distinct locations that are isolated from failures in other Availability Zones. Each subnet must reside entirely within one Availability Zone and cannot span zones.

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

VPC information you provide for host setup

When you create your host resource for your connections in the next step, you need to provide the following:

  • VPC ID: The ID of 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 ID of 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, including troubleshooting VPC or host connections, see Troubleshooting VPC configuration for your host.

Permission requirements

As part of the host creation process, AWS CodeStar Connections creates network resources on your behalf to facilitate the VPC connectivity. This includes a network interface for AWS Codestar Connections to query data from your host, and a VPC endpoint or PrivateLink for the host to send event data via webhooks to AWS CodeStar Connections. To be able to create these network resources, you must ensure the IAM user creating the host has the following permissions:

ec2:CreateNetworkInterface ec2:CreateTags ec2:DescribeDhcpOptions ec2:DescribeNetworkInterfaces ec2:DescribeSubnets ec2:DeleteNetworkInterface ec2:DescribeVpcs ec2:CreateVpcEndpoint ec2:DeleteVpcEndpoints ec2:DescribeVpcEndpoints

For more information about troubleshooting permissions or host connections in a VPC, see Troubleshooting VPC configuration for your host.

For more information about the webhook VPC endpoint, see AWS CodeStar Connections and interface VPC endpoints (AWS PrivateLink).

Create your GitHub Enterprise Server connection (console)

To create a connection to GitHub Enterprise Server, have your server URL and GitHub Enterprise credentials ready.

Step 1: Create your connection

  1. Sign in to the AWS Management Console and open the Developer Tools console at https://console.aws.amazon.com/codesuite/settings/connections.

  2. Choose Settings > Connections, and then choose Create connection.

  3. To create a connection to an installed GitHub Enterprise Server repository, choose GitHub Enterprise Server.

Connect to GitHub Enterprise Server

  1. In Connection name, enter the name for your connection.

    
                            Console screenshot showing Create host settings page with no
                                VPC.
  2. In URL, enter the endpoint for your server.

    Note

    If the provided URL has already been used to set up a GitHub Enterprise Server for a connection, you will be prompted to choose the host resource ARN that was created previously for that endpoint.

  3. If you have launched your server into an Amazon VPC and you want to connect with your VPC, choose Use a VPC and complete the following.

    1. In VPC ID, choose your VPC ID. Make sure to choose the VPC for the infrastructure where your GitHub Enterprise Server instance is installed or a VPC with access to your GitHub Enterprise Server instance through VPN or Direct Connect.

    2. Under Subnet ID, choose Add. In the field, choose the subnet ID you want to use for your host. You can choose up to 10 subnets.

      Make sure to choose the subnet for the infrastructure 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.

    3. Under Security group IDs, choose Add. In the field, choose the security group you want to use for your host. You can choose up to 10 security groups.

      Make sure to choose the security group for the infrastructure 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.

    4. If you have a private VPC configured, and you have configured your GitHub Enterprise Server instance to perform TLS validation using a non-public certificate authority, in TLS certificate, enter your certificate ID. The TLS Certificate value should be the public key of the certificate.

      
                                    Console screenshot showing create GitHub Enterprise
                                        Server connection page for VPC options.
  4. Choose Connect to GitHub Enterprise Server. The created connection is shown with a Pending status. A host resource is created for the connection with the server information you provided. For the host name, the URL is used.

  5. Choose Update pending connection.

    
                            Console screenshot showing pending GitHub Enterprise Server
                                connection page.
  6. If prompted, on the GitHub Enterprise login page, sign in with your GitHub Enterprise credentials.

  7. On the Create GitHub App page, choose a name for your app.

    
                            Console screenshot showing app creation page.
  8. On the GitHub authorization page, choose Authorize <app-name>.

    
                            Console screenshot showing app authorization page.
  9. On the app installation page, a message shows that the AWS CodeStar Connector app is ready to be installed. If you have multiple organizations, you might be prompted to choose the organization where you want to install the app.

    Choose the repository settings where you want to install the app. Choose Install.

    
                            Console screenshot showing app authorization page.
  10. The connection page shows the created connection in an Available status.