AWS Builder Center

How to integrate AWS DevOps Agent with GitHub

This guide walks you through integrating GitHub with AWS DevOps Agent so that the agent can access your code repositories and receive deployment events during incident investigations. The integration enables AWS DevOps Agent to correlate code changes with operational incidents, reducing mean time to resolution (MTTR) for any GitHub workflow failures.

The integration follows a two-step process:
  1. Account-level registration — Register GitHub once per AWS account.
  1. Agent Space connection — Connect specific repositories to individual Agent Spaces.

Prerequisites

Before you begin, verify that you have the following:
Requirement
Details
AWS DevOps Agent Agent Space
An existing Agent Space. If you haven't created one yet, see
 Creating an Agent Space 
.
AWS DevOps Agent admin console access
Permissions to access the AWS DevOps Agent console in the AWS Management Console.
GitHub admin permissions
A GitHub user account or organization with admin permissions to install GitHub Apps.
GitHub App installation authorization
Authorization to install GitHub Apps in your GitHub account or organization.

Additional prerequisites for GitHub Enterprise Server

Requirement
Details
GitHub Enterprise Server version
Version 3.x or later.
HTTPS accessibility
The instance must be accessible over HTTPS (for example,  https://github.example.com ).
Private connection (optional)
Required if your GitHub Enterprise Server instance is not publicly accessible. For more information, see
 Connecting to privately hosted tools 
.

AWS DevOps Agent Region availability

AWS DevOps Agent is available in the following AWS Regions:
  • US East (N. Virginia) —  us-east-1 
  • US West (Oregon) —  us-west-2 
  • Asia Pacific (Sydney) —  ap-southeast-2 
  • Asia Pacific (Tokyo) —  ap-northeast-1 
  • Europe (Frankfurt) —  eu-central-1 
  • Europe (Ireland) —  eu-west-1 
Ensure that your Agent Space is deployed in one of these Regions before proceeding.



Step 1: Navigate to pipeline providers

  1. Sign in to the  AWS Management Console .
  1. Navigate to the AWS DevOps Agent console.
  1. Select the Capabilities tab.
  1. In the Pipeline section, choose Add.
  1. Select GitHub from the list of available providers.
Note: If GitHub hasn't been registered at the account level yet, the console prompts you to register it first. Continue to Step 2.



Step 2: Choose the connection type

On the Register GitHub Account / Organization screen:
  1. Select the type of GitHub account you are connecting:
  • User — Your personal GitHub account with a username and profile.
  • Organization — A shared GitHub account where multiple people collaborate across projects.
  1. (GitHub Enterprise Server only) Check the Use GitHub Enterprise Server checkbox and enter the HTTPS URL of your instance (for example,  https://github.example.com ).
Important: Do not include  /api/v3  or any trailing path in the URL. Enter only the base URL.
  1. (GitHub Enterprise Server, optional) If your instance is not publicly accessible, configure a  private connection  to allow AWS DevOps Agent to securely reach your instance.
  1. Choose Submit to begin the GitHub App setup process.



Step 3: Set up the GitHub App

The setup process differs depending on whether you are connecting to GitHub.com or GitHub Enterprise Server.

Option A: GitHub.com

  1. You are redirected to GitHub to install the AWS DevOps Agent GitHub App.
  1. Select the account or organization in which to install the app.
  1. The app requests permissions to receive events from connected repositories, including deployment events.

Option B: GitHub Enterprise Server

GitHub Enterprise Server uses a GitHub App Manifest flow that automatically creates a new GitHub App on your instance. This involves two browser redirects to your GitHub Enterprise Server instance.
  1. Your browser redirects to your GitHub Enterprise Server instance's Create GitHub App page.
  1. Review the pre-filled app name. Optionally, change the name as needed.
  1. Choose Create GitHub App.
  1. You are redirected back to the AWS DevOps Agent console, which exchanges the manifest code for app credentials.



Step 4: Select repositories and complete installation

  1. On the Install & Authorize page for the GitHub App, select which repositories to grant the app access to:
  • All repositories — Grants access to all current and future repositories in the account or organization.
  • Only select repositories — Choose specific repositories from your account or organization.
  1. Choose Install & Authorize.
  1. You are redirected back to the AWS DevOps Agent console. GitHub now appears as registered at the account level.
Best practice: Follow the principle of least privilege. Grant access only to the repositories that are relevant to the applications monitored by your Agent Spaces.



Step 5: Connect repositories to an Agent Space

After registering GitHub at the account level, connect specific repositories to individual Agent Spaces:
  1. In the AWS DevOps Agent console, select your Agent Space.
  1. Go to the Capabilities tab.
  1. In the Pipeline section, choose Add.
  1. Select GitHub from the list of available providers.
  1. Select the subset of repositories relevant to this Agent Space.
  1. Choose Add to complete the connection.
Tip: You can connect different sets of repositories to different Agent Spaces based on your organizational needs — for example, aligning repositories to team responsibilities or service boundaries.



Step 6: Verify the integration

After the connection is established, verify that the integration is working:
  1. In the AWS DevOps Agent console, select your Agent Space.
  1. Go to the Capabilities tab.
  1. In the Pipeline section, confirm that the connected GitHub repositories are listed.
  1. Trigger a test deployment to one of the connected repositories to verify that AWS DevOps Agent receives deployment events.



Understanding the GitHub App

The AWS DevOps Agent GitHub App:
  • Requests access to your repositories. You can review the specific permissions during installation.
  • Receives deployment events and other repository events.
  • Allows AWS DevOps Agent to correlate code changes with operational incidents.
  • Can be uninstalled at any time through your GitHub settings.
For GitHub Enterprise Server, the GitHub App is automatically created on your instance during registration. You can manage repository access or uninstall the app at:
  • Settings → Applications → Installed GitHub Apps (to manage or uninstall)
  • Settings → Developer settings → GitHub Apps (to delete the app definition entirely)



Managing GitHub connections

Update repository access

To change which repositories the GitHub App can access:
  1. Go to your GitHub account or organization settings (or your GitHub Enterprise Server instance settings).
  1. Navigate to Installed GitHub Apps.
  1. Modify the AWS DevOps Agent app configuration.

View connected repositories

  1. In the AWS DevOps Agent console, select your Agent Space.
  1. Go to the Capabilities tab.
  1. View connected repositories in the Pipeline section.

Remove GitHub connection from an Agent Space

  1. In the Pipeline section of the Capabilities tab, select the connection.
  1. Choose Remove.

Uninstall the GitHub App completely

For GitHub.com

Uninstall the app from your GitHub account or organization settings under Installed GitHub Apps.

For GitHub Enterprise Server

Perform both of the following steps:
  1. Uninstall the app — Go to Settings → Applications → Installed GitHub Apps, choose Configure on the app, then uninstall it.
  1. Delete the app — Go to Settings → Developer settings → GitHub Apps, select the app, go to the Advanced tab, and choose Delete GitHub App.
Warning: Deleting the GitHub App on GitHub Enterprise Server is permanent and cannot be undone. If you delete it, you must re-register GitHub Enterprise Server from the beginning in the AWS DevOps Agent console to create a new app.



Security best practices

Practice
Description
Least privilege repository access
Grant the GitHub App access only to repositories relevant to your monitored applications. Avoid selecting "All repositories" unless necessary.
Review IAM role permissions
Ensure the IAM roles associated with your Agent Space follow the principle of least privilege. Use read-only permissions and restrict access to specific AWS services, resources, and Regions. For details, see
 Limiting Agent Access in an AWS Account 
.
Audit permissions regularly
Periodically review both the GitHub App permissions and the IAM policies attached to the Agent Space roles.
Use private connections for Enterprise Server
If your GitHub Enterprise Server instance is not publicly accessible, configure a private connection rather than exposing it to the internet.
Monitor with CloudTrail
All AWS DevOps Agent activities are captured by AWS CloudTrail. Enable CloudTrail logging in the hosting account for audit and compliance.



Troubleshooting

Issue
Resolution
GitHub does not appear as a registered provider
Verify that you completed the account-level registration (Steps 1–4) before attempting to connect repositories to an Agent Space.
GitHub App installation redirect fails
Ensure your browser allows pop-ups and redirects to GitHub.com or your GitHub Enterprise Server URL. Clear browser cache and retry.
Deployment events not received
Verify that the correct repositories are connected to the Agent Space. Confirm that the GitHub App has the required permissions by checking the app's settings in GitHub.
GitHub Enterprise Server connection times out
Verify that the HTTPS URL is correct and the instance is accessible. If the instance is not publicly accessible, ensure a private connection is configured.
Permission update notification not appearing
Check your GitHub notification settings. Permission update requests are sent through GitHub's built-in notification system.
Agent Space not visible in console
Confirm that you are operating in a
 supported AWS Region 
.



Related resources

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article