debian-mirror-gitlab/doc/architecture/blueprints/pods/pods-feature-contributions-forks.md

---
stage: enablement
group: pods
comments: false
description: 'Pods: Contributions: Forks'
---

This document is a work-in-progress and represents a very early state of the
Pods design. Significant aspects are not documented, though we expect to add
them in the future. This is one possible architecture for Pods, and we intend to
contrast this with alternatives before deciding which approach to implement.
This documentation will be kept even if we decide not to implement this so that
we can document the reasons for not choosing this approach.

# Pods: Contributions: Forks

[Forking workflow](../../../user/project/repository/forking_workflow.md) allows users
to copy existing project sources into their own namespace of choice (personal or group).

## 1. Definition

[Forking workflow](../../../user/project/repository/forking_workflow.md) is common workflow
with various usage patterns:

- allows users to contribute back to upstream project
- persist repositories into their personal namespace
- copy to make changes and release as modified project

Forks allow users not having write access to parent project to make changes. The forking workflow
is especially important for the Open Source community which is able to contribute back
to public projects. However, it is equally important in some companies which prefer the strong split
of responsibilites and tighter access control. The access to project is restricted
to designated list of developers.

Forks enable:

- tigther control of who can modify the upstream project
- split of the responsibilites: parent project might use CI configuration connecting to production systems
- run CI pipelines in context of fork in much more restrictive environment
- consider all forks to be unveted which reduces risks of leaking secrets, or any other information
  tied with the project

The forking model is problematic in Pods architecture for following reasons:

- Forks are clones of existing repositories, forks could be created across different organizations, Pods and Gitaly shards.
- User can create merge request and contribute back to upstream project, this upstream project might in a different organization and Pod.
- The merge request CI pipeline is to executed in a context of source project, but presented in a context of target project.

## 2. Data flow

## 3. Proposals

### 3.1. Intra-Cluster forks

This proposal makes us to implement forks as a intra-ClusterPod forks where communication is done via API
between all trusted Pods of a cluster:

- Forks when created, they are created always in context of user choice of group.
- Forks are isolated from Organization.
- Organization or group owner could disable forking across organizations or forking in general.
- When a Merge Request is created it is created in context of target project, referencing
  external project on another Pod.
- To target project the merge reference is transfered that is used for presenting information
  in context of target project.
- CI pipeline is fetched in context of source project as it-is today, the result is fetched into
  Merge Request of target project.
- The Pod holding target project internally uses GraphQL to fetch status of source project
  and include in context of the information for merge request.

Upsides:

- All existing forks continue to work as-is, as they are treated as intra-Cluster forks.

Downsides:

- The purpose of Organizations is to provide strong isolation between organizations
  allowing to fork across does break security boundaries.
- However, this is no different to ability of users today to clone repository to local computer
  and push it to any repository of choice.
- Access control of source project can be lower than those of target project. System today
  requires that in order to contribute back the access level needs to be the same for fork and upstream.

### 3.2. Forks are created in a personal namespace of the current organization

Instead of creating projects across organizations, the forks are created in a user personal namespace
tied with the organization. Example:

- Each user that is part of organization receives their personal namespace. For example for `GitLab Inc.`
  it could be `gitlab.com/organization/gitlab-inc/@ayufan`.
- The user has to fork into it's own personal namespace of the organization.
- The user has that many personal namespaces as many organizations it belongs to.
- The personal namespace behaves similar to currently offered personal namespace.
- The user can manage and create projects within a personal namespace.
- The organization can prevent or disable usage of personal namespaces disallowing forks.
- All current forks are migrated into personal namespace of user in Organization.
- All forks are part of to the organization.
- The forks are not federated features.
- The personal namespace and forked project do not share configuration with parent project.

### 3.3. Forks are created as internal projects under current project

Instead of creating projects across organizations, the forks are attachments to existing projects.
Each user forking a project receives their unique project. Example:

- For project: `gitlab.com/gitlab-org/gitlab`, forks would be created in `gitlab.com/gitlab-org/gitlab/@kamil-gitlab`.
- Forks are created in a context of current organization, they do not cross organization boundaries
  and are managed by the organization.
- Tied to the user (or any other user-provided name of the fork).
- The forks are not federated features.

Downsides:

- Does not answer how to handle and migrate all exisiting forks.
- Might share current group / project settings - breaking some security boundaries.

## 4. Evaluation

## 4.1. Pros

## 4.2. Cons