Pipelines Install via GitHub App

The Gruntwork.io GitHub App is a GitHub App introduced to help reduce the burden of integrating Gruntwork products to GitHub resources. The app is designed to be lightweight and flexible, providing a simple way to get started with Gruntwork products.

Overview

There are three major components to keep in mind when working with the Gruntwork.io GitHub App:

1. Gruntwork.io GitHub App: The Gruntwork.io GitHub App itself, which is installed in your GitHub organization.
2. GitHub App Service: The backend service that interacts with the GitHub API on behalf of the Gruntwork.io GitHub App. Outside of this page, the backend service and the GitHub App are often referred to interchangeably.
3. Clients: Clients that interact with the GitHub App Service to perform operations on GitHub resources.

Gruntwork.io GitHub App

The Gruntwork.io GitHub App is the principal that Gruntwork products will utilize to interact with GitHub resources. The app can either be installed on a per-repository basis or on an entire organization.

Required Permissions

As of 2024/09/10, the Gruntwork.io GitHub App requests the following permissions:

• Read access to Actions: Allows the app to read GitHub Actions artifacts.
• Write access to Administration: Allows the app to create new repositories, and add teams as collaborators to repositories.
• Write access to Contents: Allows the app to read and write repository contents.
• Write access to Issues: Allows the app to create and edit issues.
• Write access to Pull Requests: Allows the app to create and edit pull requests.
• Write access to Workflows: Allows the app to create and edit GitHub Actions workflow files.

Why does Gruntwork.io need these permissions?

Gruntwork.io requests all of these permissions because it requires them for different operations. Unfortunately, the way GitHub apps work prevents us from requesting permissions on a more granular basis. Know that the GitHub App Service will scope down its permissions whenever possible to the minimum required for the operation at hand.

The level of granularity available to customers when configuring the GitHub App installation is to either install the app on a per-repository basis or on an entire organization. Our recommendation is as follows:

• For non-enterprise customers, allow the app for infrastructure-live-root repository and (if in-use) infrastructure-live-access-control and infrastructure-catalog.
• For enterprise customers, allow the app to have access to the entire organization.

The reasoning for requiring entire-organization access for enterprise customers is that if you are using Account Factory to create delegated repositories then Account Factory will be creating, and then immediately modifying, new repositories in automated flows, which means it needs access to new repos as soon as they are created which is only possible with entire organization permission.

If you are unsure how to proceed here, reach out to Gruntwork Support for guidance.

Read access to Actions

Gruntwork.io needs read access to Actions in order to read GitHub Actions workflow logs.

These permissions are used when generating the dynamic Pull Request comment created when a run completes indicating the exact location in workflow run logs users need to focus their attention.

Write access to Administration

Gruntwork.io needs write access to Administration to create repositories.

These permissions are used during the initial bootstrapping process when customers opt-in to additional repositories being created outside of the main infrastructure-live-root repository.

This is especially important for DevOps Foundations Enterprise customers, as those customers benefit from the ability to have infrastructure-live-root repositories create new repositories and add designated GitHub teams as collaborators via Infrastructure as Code (IaC). This is a critical feature for Enterprise customers who want to be able to scale their infrastructure management across multiple teams with delegated responsibility for segments of their IaC Estate.

Write access to Contents

Gruntwork.io needs write access to Contents in order to propose changes to repository contents.

Pipelines engages in code generation when vending new AWS accounts in Gruntwork Account Factory, and Gruntwork.io needs to be able to generate and commit Terragrunt configuration files to the repository to provision the resources that will be present in the new account.

Write access to Issues

Gruntwork.io needs write access to Issues in order to create issues for users when it detects a problem with infrastructure.

This is a mechanism that Pipelines uses to signal to users that they need to take manual action to resolve an issue.

Write access to Pull Requests

Gruntwork.io needs write access to Pull Requests in order to create pull requests.

This is done both to propose changes in response to an explicit workflow like initiating an Account Factory vend, and to propose changes in response to detected drift detection for Enterprise customers.

Write access to Workflows

Gruntwork.io needs write access to Workflows in order to create GitHub Actions workflow files when vending GitHub repositories.

This is necessary for Enterprise account vending, as Enterprise customers have the option of vending new repositories as part of Gruntwork Account Factory vending, and the GitHub API would not allow creation of new repositories with .github/workflows files without these permissions.

Write access to Members

Gruntwork.io needs write access to Members in order to adjust the repositories that a given GitHub team has access to.

When vending delegated repositories for Enterprise customers, Gruntwork.io needs to be able to add designated GitHub teams as a collaborators to new repositories being vended.

Clients

The GitHub App Service is used by two major clients:

1. Gruntwork Developer Portal

   This is the entrypoint all Gruntwork customers use to interact Gruntwork products.

   The GitHub App Service is used here for administration of access to relevant GitHub resources by the Gruntwork.io GitHub App. Customers can follow the installation flow in the Gruntwork Developer Portal to install the Gruntwork.io GitHub App in their GitHub organization, link the GitHub app installation to their Gruntwork organization profile and configure it.

2. Gruntwork Pipelines

   The main client for the Gruntwork.io App, and where most of the value is derived. Pipelines uses the GitHub App Service to acquire the relevant access for interacting with GitHub resources on behalf of the user. Access control rules are enforced here to ensure that only the level of access required, and explicitly specified in the Gruntwork Developer Portal can be used by Pipelines to interact with GitHub resources on behalf of the user.

   For example, while the Gruntwork.io GitHub App does have permissions to create new repositories, Pipelines will only do so if a workflow originating from a configured infrastructure-live-root repository requests it.

Availability

The availability of the Gruntwork.io GitHub App is something Gruntwork will endeavor to maximize. Core to the design of the app is that day-to-day operations do not depend on the availability of the app, however.

Any downtime of Gruntwork services will not impact the ability of your team to manage infrastructure using Gruntwork products.

App Only Features

The following features of the Gruntwork.io GitHub App will be unavailable during downtime:

• GitHub App Linking: In order to link a Gruntwork.io GitHub App installation to the Gruntwork Developer Portal, the service backing the GitHub app must be available and operating correctly.
• Gruntwork Pipelines Comments: While Pipelines will allow for IaC updates in a degraded state without the availability of the GitHub App, comments are a feature that rely on the availability of the app for the best experience.
• Gruntwork Pipelines Drift Detection: Drift detection requires the availability of the GitHub App to function correctly.

Fallback

In order to ensure that the availability of the Gruntwork.io GitHub App is not something that can impair the ability of users to drive infrastructure updates, the legacy mechanism of authenticating with GitHub using Machine users is still supported.

Configuring the PIPELINES_READ_TOKEN, INFRA_ROOT_WRITE_TOKEN and ORG_REPO_ADMIN_TOKEN where necessary (following the documentation linked above) will result in Pipelines using the legacy mechanism to authenticate with GitHub, rather than the Gruntwork.io GitHub App.

Using these fallback tokens will ensure that Pipelines can continue to perform operations like:

• Plan on Pull Request open.
• Apply on Pull Request merge.
• Destroy on Pull Request merge.

Note that this will be a degraded experience, as the Gruntwork.io GitHub App provides a more feature-rich experience.

Initial Install

To install the Gruntwork.io GitHub App in your organization follow these steps.

1. Follow the instructions in the Gruntwork Developer Portal's Account Settings if you are a designated administrator.

2. Choose the GitHub Organization you want to install the App in.

   Choose GitHub Organization

3. Install in the GitHub Organization.

   Install in GitHub Organization

4. You will be redirected back to your Gruntwork Developer Portal's Account page. If the App was installed and linked with your Organization in the Developer Portal, you will get a success message like below.

   GitHub App installed and linked

Configuration

Infrastructure Live Root Repositories

DevOps Foundations treats certain repositories as especially privileged in order to perform critical operations like vending new AWS accounts and creating new repositories. These repositories are called "infrastructure live root repositories" and you can configure them in the GitHub Account section for your organization in the Gruntwork developer portal if you are a designated administrator.

Root Repository Configuration

The Gruntwork.io GitHub App will cross reference this list when attempting to perform these privileged operations. If the repository is not listed here, the Gruntwork.io GitHub App will not be able to perform these operations on your behalf.

Keeping this list up to date is critical to ensure the Gruntwork.io GitHub App can perform its duties in and only in the repositories you trust as the "root" of your infrastructure management.

For more information, see the relevant architecture documentation.

Frequently Asked Questions

How do I find my Gruntwork.io GitHub App installation ID?

You can find the installation ID of the Gruntwork.io GitHub App in the URL of the installation page.

GitHub App Installation ID