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 must have a host. A host is what your connection uses to contact the GitHub Enterprise Server instance where it is installed, such as an on-premises server, an EC2 instance, or a VPC connection.

Note

You only create a host once for your connections to a GitHub Enterprise Server account.

Prerequisites: Network or Amazon VPC configuration for your host

These steps include creating a host resource that represents the infrastructure where your GitHub Enterprise Server instance is installed, such as a server or EC2 instance on a network or VPC.

Note

You only create a host once for your connections to a GitHub Enterprise Server account.

  • If your infrastructure is configured with a network connection, have your infrastructure endpoint ready and continue to the next step: Step 1: Create your host.

  • If your infrastructure is configured with an Amazon VPC, follow these VPC requirements before you continue to the next step: Step 1: Create your host.

VPC requirements

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

Public VPC Private VPC
You can configure a public VPC with public and private 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 will provide the TLS certificate for your host resource.

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.

You can use a NAT device to enable instances in a private subnet to connect to the internet. You can use a NAT device to enable instances in a private subnet to connect to the internet.
Your VPC's subnets must reside in different Availability Zones in your Region. Availability Zones are distinct locations that are engineered to be isolated from failures in other Availability Zones. Each subnet must reside entirely within one Availability Zone and cannot span zones.
You can use the default VPC for your AWS account if you do not have preferred CIDR blocks or subnets.

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 will need to provide the following:

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

Important

AWS CodeStar Connections does not support GitHub Enterprise Server version 2.22.0 due to a known issue in the release. For more information, see the release notes Known Issues list at https://enterprise.github.com/releases/series/2.22.

Step 1: Create your host

For connections to GitHub Enterprise Server, you use a host to represent the endpoint for the infrastructure where your GitHub Enterprise Server instance is installed.

Note

You only create a host once per GitHub Enterprise Server account. All of your connections to a specific GitHub Enterprise Server account will use the same host.

To create a host

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

  2. On the Hosts tab, choose Create host.

  3. In Host name, enter the name you want to use for your host.

  4. In Select a provider, choose GitHub Enterprise Server.

  5. In Endpoint, enter the endpoint for the infrastructure where your provider is installed.

  6. If you launched your instance into an Amazon VPC and you want to connect with your VPC, choose Use a VPC. Otherwise, choose No VPC.

    
                Console screenshot showing Create host settings page with no
                    VPC.
  7. If you have launched your instance 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 host settings page for VPC
                            options.
  8. Choose Create host.

  9. After the host details page displays, the host status changes as the host is created.

    Note

    If your host setup includes a VPC configuration, allow several minutes for provisioning of host network components.

    Wait for your host to reach a Pending status, and then complete the setup. For more information, see Set up a pending host.

    
                Console screenshot showing host details with the host in Pending
                    status.

Step 2: Set up your pending host

After you create a host, use the console to set up the host to make its status Available.

To set up a pending host

After your host is created, it is in a Pending status. To move the host from Pending to Available, complete these steps. This process performs a handshake with the third-party provider to register the AWS connection app on the host.

  1. After your host reaches Pending status on the AWS Developer Tools console, choose Set up host.

  2. On the third-party installed provider login page, such as the GitHub Enterprise Server login page, log in with your account credentials if prompted.

  3. On the app install page, in GitHub App name, enter a name for the app you want to install for your host. Choose Create GitHub App.

  4. After your host is successfully registered, the host details page appears and shows that the host status is Available.

    
                Console screenshot showing the host setup is complete and in Available
                    status.
  5. You can continue with creating your connection after the host is available. On the success banner, choose Create connection. Complete the steps in Create a connection.

Step 3: Create your GitHub Enterprise Server connection resource (console)

After you have created a host resource to represent your infrastructure, and the host is in Available status, you can create your connection resource.

Step 1: Create your connection

  1. Sign in to the AWS Management Console, and open the AWS 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. In Choose a host, choose your host Amazon Resource Name (ARN).

    Choose Connect to GitHub Enterprise Server.

    
                            Console screenshot showing connection options.
  4. If you do not have a host, the You have no available hosts message displays. Choose Create host and complete the steps in Step 1: Create your host.

    
                            Console screenshot showing no host available.

After you choose to create the connection, the Connect to GitHub Enterprise Server page is shown.

Connect to GitHub Enterprise Server

  1. Under GitHub Enterprise Server Apps, choose an app installation or choose Install a new app to create one.

    Note

    You install one app for all of your connections to a particular provider. If you have already installed the GitHub Enterprise Server app, choose it and skip this step.

    
                            Console screenshot showing AWS CodeStar requests
                                access.
  2. On the GitHub authorization page, choose Authorize.

  3. On the app installation page, a message shows that the AWS app is ready to be installed. Choose Install.

  4. The connection ID for your new GitHub Enterprise Server installation is displayed. Choose Connect.