Key Features • @@ -18,16 +18,16 @@ MIT License
-Internal Contribution Forks (ICF) is GitHub App that allows you to work on contributions to an upstream open source project using a private repository in your own organization. This is useful for developing and checking contributions internally before making any commits publicly visible. +The Private Mirrors App (PMA) is GitHub App that allows you to work on contributions to an upstream open source project using a private repository in your own organization. This is useful for developing and checking contributions internally before making any commits publicly visible. For a video overview, check out [this short presentation and demo video](https://www.youtube.com/watch?v=xdiFALgHa2Y). -[](https://www.youtube.com/watch?v=xdiFALgHa2Y) +[](https://www.youtube.com/watch?v=xdiFALgHa2Y) > [!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 pre-1.0 _public beta_. We are actively working on improving it with beta testers, and if you're interested in using it for your organization, [we'd love to hear from you](https://github.com/github-community-projects/internal-contribution-forks/issues/new)! +> This app is still a work in progress and is pre-1.0 _public beta_. We are actively working on improving it with beta testers, and if you're interested in using it for your organization, [we'd love to hear from you](https://github.com/github-community-projects/private-mirrors/issues/new)! ## Background @@ -42,7 +42,7 @@ To succeed, open source advocates and OSPOs need to address their stakeholders' Addressing these concerns creates opportunities for enterprise development teams to participate more deeply in open source and foster a collaborative relationship with the open source community. -> Internal Contribution Forks (ICF) is a GitHub App paired with a UI that manages the lifecycle of private mirrors, as well as the synchronization of code between the public fork of an upstream project and the private mirrors where the enterprise teams are working. +> The Private Mirrors App (PMA) is a GitHub App paired with a UI that manages the lifecycle of private mirrors, as well as the synchronization of code between the public fork of an upstream project and the private mirrors where the enterprise teams are working. ## Key Features @@ -55,7 +55,7 @@ Addressing these concerns creates opportunities for enterprise development teams High Level Flow: - + The app uses an intermediary public fork to merge the private mirror into, and then enables the normal OSS contributor workflow into the upstream repository. This allows users to keep the private repo private while still allowing us to contribute to the upstream repository. Check out this [application flow diagram](./docs/architecture.md) for a more detailed look at how the app works. @@ -71,8 +71,8 @@ Configuration is contained in a `.env` file which you'll need to customize for y - `ALLOWED_HANDLES` variable to a comma-separated list of GitHub user handles which ought to be allowed to access the app to create mirrors. If unset, all users who are members of the organization will be allowed to use the app. ```sh -docker build -t internal-contribution-forks . -docker run --env-file=.env -p 3000:3000 internal-contribution-forks +docker build -t private-mirrors . +docker run --env-file=.env -p 3000:3000 private-mirrors # alternatively, you can use docker compose docker compose up @@ -99,7 +99,7 @@ The authentication of the UI will still need to be a user's github.com user, but ## Usage -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. +Once the app is installed, follow this document on [Using the Private Mirrors App](docs/using-the-app.md) to get the repository fork and mirrors set up for work. ## Developing @@ -162,7 +162,7 @@ Check out the [CODEOWNERS](./CODEOWNERS) file to see who to contact for code cha ## Support -If you need support using this project or have questions about it, please [open an issue in this repository](https://github.com/github-community-projects/internal-contribution-forks/issues/new) and we'd be happy to help. Requests made directly to GitHub staff or the support team will be redirected here to open an issue. GitHub SLA's and support/services contracts do not apply to this repository. +If you need support using this project or have questions about it, please [open an issue in this repository](https://github.com/github-community-projects/private-mirrors/issues/new) and we'd be happy to help. Requests made directly to GitHub staff or the support team will be redirected here to open an issue. GitHub SLA's and support/services contracts do not apply to this repository. ## More OSPO Tools diff --git a/SUPPORT.md b/SUPPORT.md index eba3993..39927f8 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,7 +6,7 @@ This project uses GitHub issues to track bugs and feature requests. Please searc For help or questions about using this project, please file an issue or start a GitHub discussion. -Internal Contribution Forks is under active development and maintained by GitHub staff **and the community**. We will do our best to respond to support, feature requests, and community questions in a timely manner. +The Private Mirrors app is under active development and maintained by GitHub staff **and the community**. We will do our best to respond to support, feature requests, and community questions in a timely manner. ## GitHub Support Policy diff --git a/app.yml b/app.yml index 7e7e034..0c4d8a0 100644 --- a/app.yml +++ b/app.yml @@ -71,13 +71,13 @@ default_permissions: organization_custom_properties: admin # The name of the GitHub App. Defaults to the name specified in package.json -name: internal-contribution-forks +name: private-mirrors # The homepage of your GitHub App. -url: https://github.com/github-community-projects/internal-contribution-forks +url: https://github.com/github-community-projects/private-mirrors # A description of the GitHub App. -description: A GitHub App that allows you to contribute upstream using a "private fork". +description: A GitHub App that allows you to contribute upstream using private mirrors of public repos. # Set to true when your GitHub App is available to the public or false when it is only accessible to the owner of the app. Default: true public: true diff --git a/docs/using-the-app.md b/docs/using-the-app.md index 6e98bfb..771309e 100644 --- a/docs/using-the-app.md +++ b/docs/using-the-app.md @@ -1,8 +1,8 @@ -## How to get started working with Internal Contribution Forks +## How to get started working with the GitHub Private Mirrors App (PMA) 1. Set up an organization to host your open source work. Many enterprises use a primary organization which mainly contains private repos or company-wide projects owned by the enterprise. Creating a separate organization which hosts your open-source efforts - both forks of upstream projects in use for this app, as well as open projects that expect a lot of external collaborators - makes for cleaner administrative/security boundaries. -2. Install the app into that organization. Currently you'll need to self-host the application, following the [instructions in the project's README](../README.md), but we are working towards a hosted solution as well - if this is a blocker for you please comment on [this issue](https://github.com/github-community-projects/internal-contribution-forks/issues/122) to register your interest and say more about your use case. +2. Install the app into that organization. Currently you'll need to self-host the application, following the [instructions in the project's README](../README.md), but we are working towards a hosted solution as well - if this is a blocker for you please comment on [this issue](https://github.com/github-community-projects/private-mirrors/issues/122) to register your interest and say more about your use case. 3. Fork an upstream project into the organization's namespace. This will create your **public fork**. A decision point for administrators is whether to permit any user to fork new projects into the organizations, or restrict the ability to fork. These permissions are managed by [the organization's forking policy](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization). A more permissive posture can lower the barrier to contribution, but be careful not to circumvent company policy on approving upstream work. @@ -10,7 +10,7 @@  -5. Click on the name of the public fork you just created. Click **Create mirror** and give it an unambiguous name, then click **Confirm**. This will create a **private mirror** of the repo. The app syncs commits on the private mirror's default branch to a new branch on the public fork. For example, the default branch of a private mirror named `silverteam-website` will be synced to a branch named `silverteam-website` on the public fork. So it's a good idea to be verbose in your name and describe how this fork will be used. ICF's workflow supports multiple private mirrors per public fork, to enable different individuals or teams to work on the default branches of their respective mirrors without interefering with each other. +5. Click on the name of the public fork you just created. Click **Create mirror** and give it an unambiguous name, then click **Confirm**. This will create a **private mirror** of the repo. The app syncs commits on the private mirror's default branch to a new branch on the public fork. For example, the default branch of a private mirror named `silverteam-website` will be synced to a branch named `silverteam-website` on the public fork. So it's a good idea to be verbose in your name and describe how this fork will be used. PMA's workflow supports multiple private mirrors per public fork, to enable different individuals or teams to work on the default branches of their respective mirrors without interefering with each other. 