Basic installation on AWS requires using the EC2 management tools to launch an instance of the GitHub Enterprise AMI. The instance may be launched into either EC2-Classic or your organization's VPC. To store Git repositories, databases, and other application data, you must create and attach a separate EBS root volume.
Instructions on launching an instance designed to meet the needs of your organization are detailed below.
Requirements
Before installing GitHub Enterprise on AWS, ensure you meet these software and hardware requirements.
Software
- You must have an AWS account capable of launching EC2 instances and creating EBS volumes. Sign up here.
- You must have a GitHub Enterprise license file. To download an existing license file or request a trial license, visit enterprise.github.com.
Additionally, this guide assumes you are familiar with the following AWS concepts:
- Launching EC2 Instances.
- Managing EBS Volumes.
- Using Security Groups. For managing network access to your instance.
- Elastic IP Addresses (EIP). Strongly recommended for production environments.
- EC2 and Virtual Private Cloud. If you plan to launch into a VPC.
Most actions needed to launch your instance may be performed using either the AWS management console or the AWS Command Line Interface. Examples using the command line interface are included below. We recommend installing the command line tools for initial setup and using the examples provided if this is your first time launching an instance on AWS.
Hardware
Based on your seat count, we recommend this hardware configuration:
| Seats | vCPUs | Memory | Attached Storage | Root Storage |
|---|---|---|---|---|
| 10-500 | 2 | 16 GB | 100 GB | 200 GB |
| 500-3000 | 4 | 32 GB | 250 GB | 200 GB |
| 3000-5000 | 8 | 64 GB | 500 GB | 200 GB |
| 5000-8000 | 12 | 72 GB | 750 GB | 200 GB |
| 8000-10000+ | 16 | 128 GB | 1000 GB | 200 GB |
These are minimum recommendations. More resources may be required depending on your usage, such as user activity and selected integrations.
Note: The root disk can be resized by building a new appliance. For more information, see "Increasing storage capacity."
Warning: We recommend you use webhooks to fetch repository changes for continuous integration (CI) or similar systems. Regular automatic checks, or polling, will significantly reduce the scalability of your instance.
Determining the instance type
Before launching your GitHub Enterprise instance on AWS, you'll need to determine the type of virtual machine that best fits the needs of your organization.
Supported Instance Types
GitHub Enterprise is supported on the following EC2 instance types:
- m3.xlarge
- m3.2xlarge
- m4.xlarge
- m4.2xlarge
- c3.2xlarge
- c3.4xlarge
- c3.8xlarge
- c4.2xlarge
- c4.4xlarge
- c4.8xlarge
- r3.large
- r3.xlarge
- r3.2xlarge
- r3.4xlarge
- r3.8xlarge
- r4.large
- r4.xlarge
- r4.2xlarge
- r4.4xlarge
- r4.8xlarge
- r4.16xlarge
Note: R4 instances are only supported for GitHub Enterprise versions 2.8.7 or higher.
For more information, see the AWS EC2 instance type overview page.
Recommended instance types
Based on your seat count, we recommend these instance types:
| Seat Range | Recommended Type |
|---|---|
| 10 - 500 | r3.large |
| 500 - 3000 | r3.xlarge |
| 3000 - 5000 | r3.2xlarge |
| 5000 - 8000 | r3.4xlarge |
| 8000 - 10000+ | r3.8xlarge |
Note: You can always scale up your CPU or memory by resizing your instance. However, because resizing your CPU or memory requires downtime for your users, we recommend over-provisioning resources to account for scale.
Selecting the GitHub Enterprise AMI
Using the GitHub Enterprise Portal to select an AMI
- Browse to https://enterprise.github.com/download.
- Click Get the latest release of GitHub Enterprise.
- Select Amazon Web Services in the Select your platform dropdown.
- Select your desired region in the Select your AWS region dropdown.
- Take note of the AMI ID that is displayed.
Using the AWS CLI to select an AMI
Use the AWS CLI to get a list of GitHub Enterprise images published by GitHub's AWS owner IDs (025577942450 for GovCloud and 895557238572 for other regions).
aws ec2 describe-images \
--owners OWNER ID \
--query 'sort_by(Images,&Name)[*].{Name:Name,ImageID:ImageId}' \
--output=text
Using the AWS Management Console to select an AMI
- On the left side of the EC2 Dashboard under IMAGES, click AMIs.
- Select Public images from the search dropdown.
- Click the search field and select Owner to add a filter.
- Type GitHub's owner ID (025577942450 for GovCloud and 895557238572 for other regions) in the owner filter and press Enter.
Support for GovCloud
AMIs for GitHub Enterprise are available in the AWS GovCloud (US) region. This allows US customers with specific regulatory requirements to run GitHub Enterprise in a federally compliant cloud environment.
For more information on AWS's compliance with federal and other standards, see AWS's compliance page.
Creating a Security Group
If you're setting up your AMI for the first time, you will need to create a security group. From the EC2 Management Console, create an entry for each port in the table below:
| Port | Service | Description |
|---|---|---|
| 22 | SSH | Git over SSH access. Clone, fetch, and push operations to public/private repositories supported. |
| 25 | SMTP | SMTP with encryption (STARTTLS) support. |
| 80 | HTTP | Web application access. Note that all requests are redirected to the HTTPS port when SSL is enabled. |
| 122 | SSH | Instance shell access. Note that the default SSH port (22) is dedicated to application git+ssh network traffic. |
| 161/UDP | SNMP | Required for network monitoring protocol operation. |
| 443 | HTTPS | Web application and Git over HTTPS access. |
| 1194/UDP | VPN | Secure replication network tunnel in High Availability configuration. |
| 8080 | HTTP | Plain-text web based Management Console. Not required unless SSL is disabled manually |
| 8443 | HTTPS | Secure web based Management Console. Required for basic installation and configuration. |
| 9418 | Git | Simple Git protocol port. Clone and fetch operations to public repositories only. Unencrypted network communication. |
Take note of the security group ID (sg-xxxxxxxx) of your newly created security group.
Launching an EC2 instance
Use the AWS management console or command line tools to launch an EC2 instance with the values determined in the previous steps. For example, to launch an r3.xlarge instance with 100 GB EBS volume in the us-east-1 region, you would run the following command:
aws ec2 run-instances \
--security-group-ids SECURITY GROUP ID \
--instance-type r3.xlarge \
--image-id AMI ID \
--block-device-mappings '[{"DeviceName":"/dev/xvdf","Ebs":{"VolumeSize":100,"VolumeType":"gp2"}}]' \
--region us-east-1 \
--ebs-optimized
Enabling EBS encryption
An encrypted data volume provides an extra level of security by ensuring that any data you write to your instance is protected. There's a slight peformance impact when using encrypted disks. If you decide to encrypt your volume, we strongly recommend doing so before starting your instance for the first time. For more information, see the guide on Amazon EBS encryption.
If you decide to enable encryption after you've configured your instance, you will need to migrate your data to the encrypted volume, which will incur some downtime for your users.
Allocating an Elastic IP and associate it with the instance
If this is a production instance, we strongly recommend allocating an Elastic IP (EIP) and associating it with the instance before proceeding to GitHub Enterprise configuration. Otherwise, the public IP address of the instance will not be retained after instance restarts.
Both primary and replica instances should be assigned separate EIPs in production High Availability configurations.
Starting the instance
- Once your instance is running, copy the VM's public DNS name and paste it into a web browser.
- Configure the GitHub Enterprise appliance.
