Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs to include information about GHEC integration #47

Merged
merged 2 commits into from
Feb 23, 2024
Merged

Update docs to include information about GHEC integration #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88cbe63
docs: update docs to include information about GHEC integration
ajhenry Feb 22, 2024
1dd59da
Update README.md
ajhenry Feb 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 26 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@

This is a Next.js project with an accompanying GitHub App that allows you to contribute to an upstream project using a private repository in your own organization. This is useful for organizations that want to keep their code private and perform their own checks before making any code changes public.

> [!WARNING]
> [!IMPORTANT]
> 📣 EMU support is now available! Check out the [hosting - GHEC](#integrating-the-app-into-ghec) section for more information.
>
> This app is still a work in progress and is not considered stable just yet. We still recommend trying out the app because [we'd love to hear from you](https://github.com/github-community-projects/internal-contribution-forks/issues/new)!

## Background
Expand All @@ -39,6 +41,7 @@ Solving these concerns creates opportunities for enterprise development teams to
- No datastore — no need to worry about storing your code on a third-party server
- Reduces risk of making open source contributions to upstream projects because your work stays private until it passes approval
- Adapt the app to your workflow to ensure approvals, checks, and other requirements are met before code is merged upstream
- Works with GitHub Enterprise Managed Users (EMUs) and GitHub Enterprise Cloud (GHEC)

High Level Flow:

Expand All @@ -65,7 +68,7 @@ The app uses an intermediary public fork to merge the private mirror into, and t

## Hosting

The app is not yet available on the GitHub Marketplace. We are working on that and will update this section once it is available. Until then, you'll need to self-host the app. See the section on [Developing](#developing) for more information.
You'll need to self-host the app. See the section on [Developing](#developing) for more information.

This app was created with the idea of self-hosting in mind and can be deployed to any hosting provider that supports Next.js/Docker.

Expand All @@ -75,15 +78,30 @@ You will still need to create a GitHub App and configure it to point to your dep
docker build -t internal-contribution-forks .
docker run --env-file=.env -p 3000:3000 internal-contribution-forks

# alternatively, you can use docker-compose
docker-compose up
# alternatively, you can use docker compose
docker compose up
```

We recommend using Node 20.x or higher, though any Node LTS version should work.
We recommend using Node 20.x or higher, though any Node LTS version >18 should work.

## Integrating the App into GHEC

The app can be integrated into GitHub Enterprise Cloud (GHEC) by following the same steps as GitHub.com. The app is designed to work with GHEC and GitHub Enterprise Managed Users (EMUs).

The only tradeoff is that a single app instance will only work between a single GitHub instance and a single GHEC instance. If you have multiple GitHub instances and GHEC instances, you will need to deploy multiple instances of the app.

To enable the app to work with GHEC, you will need to set the following environment variables in addition to installing the App on your GHEC organization instance.

```sh
PUBLIC_ORG=name-of-your-public-org # Where your public forks will be created
PRIVATE_ORG=name-of-your-ghec-org # Where your private mirrors will be created
```

The authentication of the UI will still need to be a user's github.com user, but the app will be able to create forks and mirrors in the GHEC instance.

## Usage

Once the app is installed, follow this document on [docs/using-the-app.md](Using the ICF App) to get the repository fork and mirrors set up for work.
Once the app is installed, follow this document on [Using the ICF App](docs/using-the-app.md) to get the repository fork and mirrors set up for work.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ack, good catch !


## Developing

Expand Down Expand Up @@ -133,11 +151,11 @@ Copy the URL and paste it into the `WEBHOOK_PROXY_URL` environment variable in `

We recommend that you have a dedicated GitHub organization for your contributions. This will allow you to keep your contributions separate from your organization's daily operations.

> 📣 This does not work with EMU accounts or GHES at this time. Please follow [this issue](https://github.com/github-community-projects/internal-contribution-forks/issues/12) for more updates.
> We have added support for GitHub Enterprise Managed Users (EMUs) and GitHub Enterprise Cloud (GHEC) in the app. If you are using GitHub Enterprise, you will need to make sure that the app is installed on your GitHub Enterprise instance.

Permissions:

- The GitHub App must be installed on the organization you plan on contributing from
- The GitHub App must be installed on the organization(s) you plan on contributing from
- Currently, any member of the organization can access the app and create additional private mirror repositories

## License
Expand Down
27 changes: 25 additions & 2 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,34 @@

The project is a Node.js application that uses the [Probot framework](https://probot.github.io/) to listen for events from GitHub. It uses a GitHub App to perform elevated actions on behalf of the user while the user has little or no permissions at all.

## Sequence Diagram
## EMU Flow

```mermaid
sequenceDiagram
participant U as upstream *Public
box github.com/your-organization
box github.com/public-organization
participant F as fork *Public
end
box github.com/emu-organization
participant M as mirror *Private
end
U->>F: User forks upstream into Organization
F-->>F: Bot creates branch protection rules
F-->>F: User requests mirror to be made
F->>M: Bot creates a mirror of the fork
M-->>M: Bot creates branch protection rules
M-->>M: User makes all changes in non-default branches
M-->>M: User merges into `default` branch
M->>F: Bot automatically syncs mirror to fork
F->>U: User opens PR to upstream
```

## Single Organization Flow

```mermaid
sequenceDiagram
participant U as upstream *Public
box github.com/your-public-organization
participant F as fork *Public
participant M as mirror *Private
end
Expand All @@ -18,6 +40,7 @@ sequenceDiagram
F-->>F: User requests mirror to be made
F->>M: Bot creates a mirror of the fork
M-->>M: Bot creates branch protection rules
M-->>M: User makes all changes in non-default branches
M-->>M: User merges into `default` branch
M->>F: Bot automatically syncs mirror to fork
F->>U: User opens PR to upstream
Expand Down