Create a connection to GitHub Enterprise Cloud with data residency
You can use the AWS Management Console or the AWS Command Line Interface (AWS CLI) to create a connection to
repositories in an enterprise on GitHub Enterprise Cloud with data residency. Each enterprise on GitHub Enterprise Cloud with data residency has
its own subdomain on GHE.com, such as https://my-enterprise.ghe.com.
Before you begin:
-
You must have an enterprise on GitHub Enterprise Cloud with data residency. Its URL must have the form
https://and must use HTTPS.subdomain.ghe.com -
You must have at least one organization set up in your enterprise.
-
You must be an organization owner of the organization where you install the AWS Connector for GitHub app. You don't need to be an enterprise owner.
-
You must install the app on an organization, not on a personal account. For more information, see Abilities and restrictions of managed user accounts
in the GitHub documentation.
The AWS Connector for GitHub app is already available on GitHub Enterprise Cloud with data residency. You don't need to register or create a GitHub App in your enterprise.
Connection resource is replicated across AWS Regions within a partition to provide cross-region connection sharing. If you need further isolation, use opt-in region or non-commercial partitions.
CodeConnections supports connections to GitHub Enterprise Cloud with data residency (*.ghe.com) tenants. Not every AWS service that uses CodeConnections supports this provider type yet. Before you use a GitHub Enterprise Cloud with data residency connection with another AWS service, check that service's documentation to confirm it supports the provider type.
Topics
Create a connection to GitHub Enterprise Cloud with data residency (console)
In the following procedure, you choose the GitHub Enterprise Cloud with data residency provider and enter the URL of your enterprise on GHE.com. The connection is created in Pending status.
To create the connection
-
Sign in to the AWS Management Console.
-
Open the Developer Tools console at https://console.aws.amazon.com/codesuite/settings/connections
. -
On the Connections page, choose Create connection.
-
On the Create a connection page, under Select a provider, select GitHub Enterprise Cloud with data residency.
-
Enter the details for the connection:
-
Under Connection Settings, in Connection name, enter the name for the connection that you want to create.
-
Under Connection Settings, in URL, enter the URL of your enterprise on GHE.com, such as
https://my-enterprise.ghe.com. -
(Optional) Under Tags, add tags for the connection.
-
-
At the bottom of the page, choose Connect to GitHub Enterprise Cloud.
The connection details page for your connection opens, and a message confirms that you created the connection.
-
Under Connection settings, confirm that Status shows Pending, Provider shows GitHub Enterprise Cloud, and Endpoint shows the URL of your enterprise. The Finish creating your connection banner contains the Update pending connection button that you use in the next procedure.
Your connection now exists in Pending status. To continue, complete the procedure To complete the connection.
In the following procedure, you authorize the AWS Connector for GitHub app, install it on an organization in your enterprise, and complete the connection. Complete all the steps in one session. If you leave before you finish, start again from Update pending connection. When you complete the connection, its status changes to Available, and you can use the connection.
To complete the connection
-
If the connection details page for your connection isn't open, open the Developer Tools console at https://console.aws.amazon.com/codesuite/settings/connections
. On the Connections page, select the connection that you created, and then choose View details. -
On the connection details page, in the Finish creating your connection banner, choose Update pending connection. If you aren't already signed in to your enterprise on GHE.com, sign in with your credentials.
-
On the Select user to authorize AWS Connector for GitHub page, for the account that you're signed in as, choose Continue. To use another listed account, choose Select for that account. To use an account that isn't listed, choose Use a different account.
NoteOn GHE.com, the developer of the AWS Connector for GitHub app appears as
github-third-party-apps-ownerinstead of AWS CodeConnections. This is expected.
The Connect to GitHub Enterprise Cloud page opens in the console.
-
On the Connect to GitHub Enterprise Cloud page, under GitHub Apps, do one of the following:
-
If the AWS Connector for GitHub app isn't installed on the organization that you want to use, choose Install a new app. You install the app once for each organization.
-
If the app is already installed on the organization, select the existing installation from the list, choose Connect, and then go to the last step of this procedure.
-
-
On the Install AWS Connector for GitHub page in your enterprise, under Where do you want to install AWS Connector for GitHub?, choose the organization where you want to install the app.
NoteIf you receive an insufficient permissions error when you install the app, see Unable to install the app for a GitHub Enterprise Cloud with data residency connection because of insufficient permissions.
-
On the Install & Authorize AWS Connector for GitHub page, under for these repositories, select All repositories or Only select repositories. If you select Only select repositories, select at least one repository.
-
Under with these permissions, review the read and write access that the app requests, and then choose Install & Authorize.
-
On the Connect to GitHub Enterprise Cloud page, under GitHub Apps, your new installation is selected. Choose Connect.
-
On the connection details page, under Connection settings, confirm that Status shows Available. Your connection is ready to use.
Create a connection to GitHub Enterprise Cloud with data residency (CLI)
You can use the AWS Command Line Interface (AWS CLI) to create a connection to GitHub Enterprise Cloud with data residency.
To do this, use the create-connection command.
A connection created through the AWS CLI is in PENDING status by
default. After you create a connection with the AWS CLI, use the console to edit the
connection to make its status AVAILABLE.
The following procedure creates a connection to GitHub Enterprise Cloud with data residency in
PENDING status. You then use the console to authorize and install the AWS
Connector for GitHub app on an organization and make the connection
AVAILABLE.
To create a connection to GitHub Enterprise Cloud with data residency
-
Open a terminal (Linux, macOS, or Unix) or command prompt (Windows). Use the AWS CLI to run the create-connection command, specifying the
--provider-type,--provider-endpoint, and--connection-namefor your connection. In this example, the third-party provider name isGitHubEnterpriseCloudDataResidency, the provider endpoint is the URL of the enterprise,https://my-enterprise.ghe.com, and the specified connection name isMyConnection.aws codeconnections create-connection --provider-type GitHubEnterpriseCloudDataResidency --provider-endpoint "https://my-enterprise.ghe.com" --connection-name MyConnectionIf successful, this command returns the connection ARN information similar to the following.
{ "ConnectionArn": "arn:aws:codeconnections:us-west-2:account_id:connection/aEXAMPLE-8aad-4d5d-8878-dfcab0bc441f" } -
Use the console at https://console.aws.amazon.com/codesuite/settings/connections
to authorize and install the AWS Connector for GitHub app and complete the connection. Follow the procedure To complete the connection in Create a connection to GitHub Enterprise Cloud with data residency (console).