How to create an internal score fork [DRAFT]

[AlexanderLanin]

⚠️ Disclaimer: This is a first ChatGPT-generated draft.
Needs scope alignment. Do we want to describe the two-org approach here?

Forking the SCORE Organization: Public & Private Forks

Partners working with SCORE typically need two forks:

1. a public fork to contribute upstream via PRs
2. a private/internal fork to integrate SCORE with company systems (CI/CD, compliance, secrets).

This guide introduces the concept at three levels of detail:

• Executive level: why both forks matter
• Normal level: typical workflows and contribution models
• Implementation level: sync, branches, and protections (only inline comments, no full scripts)

---

1. Executive Level (Why)

• Public forks keep contributions visible and upstreamable.
• Private forks allow integration with proprietary code and internal policies.
• Two contribution models exist:
  • Internal-first (gated): private review before public PR.
  • Public-first (open): direct contribution via public fork.
• Tradeoff: Internal-first = compliance/confidentiality; Public-first = velocity/community collaboration.

---

2. Normal Level (What)

Fork Types

• Public Forks

  • For feature branches and PRs only.
  • Must remain clean and minimal.

• Private/Internal Forks

  • Host mirrored upstream branches (main, release/*).
  • Contain company-specific branches (internal/main, internal/feature/*).
  • Enforce internal CI/CD, CODEOWNERS, and compliance.

Contribution Models

• Internal-first (gated):

  • Flow: dev → internal PR → internal review → promote branch → public fork → upstream PR.
  • Pros: compliance, confidentiality.
  • Cons: slower, more complex.

• Public-first (open):

  • Flow: dev → public fork feature branch → upstream PR.
  • Pros: fast, transparent, community-friendly.
  • Cons: needs guardrails to avoid leaks.

---

3. Implementation Level (How)

Repo Sync

• Initial seed: a one-time full mirror into an empty private repo.
• Ongoing sync: explicitly push upstream branches (e.g., main, release/*) into private fork; avoid overwriting internal/*.
• Avoid git push --mirror except at initial seed or for read-only mirrors.

Branch Layout

• main, release/* → upstream mirrors (bot-only updates).
• internal/* → private company branches.
• feature/* → short-lived public fork branches for upstream PRs.

Protections & Policies

• Public fork:
  • No secrets.
  • Basic lint/format/build/test checks.
• Private fork:
  • Internal CI with compliance/security.
  • Protect upstream branches.
  • Require CODEOWNERS + review on internal/*.

Promotion Flow

• Internal-first:
  • Rebase internal feature branch onto upstream main.
  • Strip internal-only commits/files if needed.
  • Push result into public fork, open PR upstream.

CI Hooks

• Internal PRs: run full secret-backed compliance checks.
• Public PRs: run open CI checks only.
• Optional: trigger internal CI on public PR head (read-only, no secret leaks).

---

TL;DR

• Always keep two forks:
  • Public fork = upstream PRs.
  • Private fork = integration & compliance.
• Choose a contribution model:
  • Internal-first = safer but slower.
  • Public-first = faster but riskier.
• Protect mirrored upstream branches; keep internal work separate.
• Automate syncs, document policies, and define responsibilities.

[opajonk]

Good initiative!

For "public first" I think it could be sufficient to have only that public fork. At least for initial & simple contributions. Or at least one could start with only public, then public/internal.

Additional / more detailed reasons for internal forks I can think of:

• You must have control over the source code you use for customers and not depend on external repositories which at least in theory can disappear at any time (a special case "of compliance").
• You are a distributor / integrator and add something on top of S-CORE (all special cases of "company-specific branches"):
  • automated packaging for special purposes,
  • custom integration & system tests which depend on hardware and/or code that are not possible to open source (unit tests you hopefully open source!),
  • proprietary modules or glue-code which cannot be open sourced for business reasons,
  • customer specific modifications that no one else will be interested in or that cannot be open sourced,
  • bug-fixes that are not yet up-streamed for whatever reason (but hopefully are in the process of being up-streamed!),
  • support branches for older releases that you maintain on top of what the OSS project already does

[dcalavrezo-qorix]

Here is how we do it at Qorix : we have a dedicated publishing workflow for internal forks, triggered manually, whenever we want to align/push.

Qorix Pseudo-fork Publisher Workflow

We have a repository that provides a GitHub Action workflow to automate publishing a development branch from an internal repository to a public fork. It's designed for projects where internal code is staged before being contributed to an upstream open-source repository.

---

📘 Background: Why Use a Private Repository in Addition to a Public Fork?

In our development model, we use three repositories per project:

• repo_internal — our private internal repo where development happens securely.
• qorix-group/repo — our public fork, shared openly on GitHub.
• eclipse-score/repo — the original open-source repo, to which we contribute via pull requests.

Naming Convention

We follow a strict naming convention to simplify automation:

• The private working repository (or pseudo-fork) must have the suffix _internal, e.g. inc_orchestrator_internal
• The public fork shares the same name as the original repo, e.g. inc_orchestrator

Why this structure?

• 🔒 Internal development is protected and private.
• 🧼 Public forks remain clean, reviewable and stripped of internal tooling.
• 🔁 Pull Requests (PRs) require the source branch to have a common ancestor with the base repository — meaning the fork must share history with the original.

Visual Diagram:

inc_orchestrator_internal (private)
        │
        ▼  ➝ publish branch ➝ e.g. feature/myfix
qorix-group/inc_orchestrator (public fork)
        │
        ▼  Pull Request ➝ base: main
 eclipse-score/inc_orchestrator (upstream)

---

🔐 Using a GitHub App for Secure Automation

To avoid using personal access tokens (PATs) and to enable secure automation at the org level, we use a GitHub App - the qorix-repo-publisher.

✅ Why Use a GitHub App?

• App tokens are short-lived and more secure.
• Scoped installation access to only the repositories it needs.
• Supports automation across private and public repos.

🛠 How it was Set Up

1. Go to GitHub → Developer Settings → GitHub Apps
2. Create a GitHub App (we use qorix-repo-publisher)
3. Grant access to both:
   • qorix-group/inc_orchestrator_internal
   • qorix-group/inc_orchestrator
4. Generate a private key and save it as a GitHub secret:
   • GH_APP_ID: the numeric App ID
   • GH_APP_PRIVATE_KEY: contents of the generated .pem file

🛠 Request access

If new repos are created, request INFRA team to install the app on the new repos.

🔑 Token Generation in Workflow

In your workflow, generate a scoped token using the tibdex/github-app-token action:

- name: Generate GitHub App token
  id: generate_token
  uses: tibdex/github-app-token@v2
  with:
    app_id: ${{ secrets.GH_APP_ID }}
    private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}

This token is then used in subsequent steps to clone, fetch, or push to repos securely.

---

⚙️ What This Workflow Does

This GitHub Action:

1. Checks out the internal repo (e.g., inc_orchestrator_internal)
2. Fast-forwards its main branch to match the latest from upstream (eclipse-score/inc_orchestrator)
3. Creates a feature branch and pushes it to the public fork (qorix-group/inc_orchestrator)
4. (Optionally) verifies the branch exists and is PR-ready

The branch can then be used to open a PR into the upstream project.

---

▶️ How to Run

This workflow is manually triggered via GitHub Actions UI.

Input Parameters

• repo_slug: Select which project (e.g. inc_orchestrator)
• source_branch: The branch to base changes on (e.g. main)
• dest_branch: The name of the branch to push to the public fork (e.g. feature/myfix)

Example Trigger UI

Repo:         [inc_orchestrator ▾ ]
Source:       main
Destination:  feature/myfix
▶ Run Workflow

---

📎 Example Use Case

You finished your work in the internal repo and want to open a Pull Request to upstream. You:

1. Run this workflow with dest_branch=myfeature
2. Go to qorix-group/inc_orchestrator ➝ create PR ➝ base: eclipse-score/inc_orchestrator/main
3. Submit your PR from the branch you just published

---

🧑‍💻 Manual Workflow Using Git Only

For developers who prefer working locally, here is how to achieve the same result manually with Git.

Step-by-step:

# 1. Clone the internal repo
$ git clone [email protected]:qorix-group/inc_orchestrator_internal.git
$ cd inc_orchestrator_internal

# 2. Add upstream and fork remotes
$ git remote add upstream https://github.com/eclipse-score/inc_orchestrator.git
$ git remote add fork https://github.com/qorix-group/inc_orchestrator.git

# 3. Sync internal/main with upstream/main
$ git fetch upstream
$ git checkout main
$ git merge --ff-only upstream/main

# 4. Create and push your branch to the public fork
$ git checkout -b feature/my_branch
$ git push fork HEAD:feature/my_branch

After pushing, navigate to your public fork on GitHub and open a Pull Request from feature/my_branch into the upstream repository.

---

Optional alternative:Using Copybara for Repo Sync

What is Copybara?

Copybara is an open-source tool developed by Google that helps synchronize code between repositories. It's built to support workflows where you need to:

• Mirror code across internal and external repos
• Filter out unwanted files
• Transform file content or commit metadata
• Keep histories clean and consistent

---

✅ Key Benefits of Copybara

1. Iterative (Non-squash) Commits

By default, Copybara supports both squash and iterative commit models. We use the ITERATIVE mode to:

• Retain individual commits
• Preserve commit messages and timestamps
• Avoid compressing change history into one lump commit

2. File Filtering

You can configure Copybara to:

• Exclude internal-only files (e.g., .github/workflows, copy.bara.sky, credentials)
• Include only open-source-relevant content

This ensures your public fork stays clean.

3. Author Preservation

Using:

authoring = authoring.pass_thru("Qorix Bot <[email protected]>")

Copybara keeps the original commit authors — important for traceability and contribution credit.

4. Transformations

Copybara supports custom transformations such as:

• core.replace, core.move, core.transform
• Injecting headers
• Renaming folders

Example:

transformations = [
  core.replace(
    before = "INTERNAL_PATH",
    after = "PUBLIC_PATH",
  )
]

---

Example: Minimal Copybara Config

origin = git.origin(
    url = "https://github.com/qorix-group/inc_orchestrator_internal.git",
    ref = "main",
)

destination = git.destination(
    url = "https://github.com/qorix-group/inc_orchestrator.git",
    fetch = "refs/heads/main",
    push = "refs/heads/{{BRANCH}}",
)

core.workflow(
    name = "publish_branch",
    mode = "ITERATIVE",
    origin = origin,
    origin_files = glob(
        ["**"],
        exclude = [
            "copy.bara.sky",
            "sync.sky",
            ".github/workflows/copybara.yml",
            ".github/workflows/sync.yml",
        ],
    ),
    destination = destination,
    authoring = authoring.pass_thru("Qorix Bot <[email protected]>"),
    transformations = [],
)

---

CI Example: Running Copybara in GitHub Actions

- name: Generate GitHub App token
  id: generate_token
  uses: tibdex/github-app-token@v2
  with:
    app_id: ${{ secrets.GH_APP_ID }}
    private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}

- name: Configure Git
  run: |
    git config --global user.name  "Qorix Bot"
    git config --global user.email "[email protected]"
    echo "https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com" > ~/.git-credentials

- name: Run Copybara
  run: |
    sed -i "s/{{BRANCH}}/${{ github.event.inputs.branch_name }}/g" copy.bara.sky
    curl -LO https://github.com/qorix-group/copybara/releases/download/v20250508/copybara_deploy.jar
    java -jar copybara_deploy.jar migrate copy.bara.sky publish_branch

---

Local Usage

You can also run Copybara manually on your local machine:

$ java -jar copybara_deploy.jar --init-history --force copy.bara.sky publish_branch

Use this to preview migrations or sync new branches outside CI.

Check the copybara directory for some configuration examples.

Challenges of Using Copybara in GitHub Actions (CI)

While Copybara works well locally, it's tricky to use in GitHub Actions, which automate tasks when code changes:

❌ It doesn’t support GitHub’s default token system.

❌ It expects stored state (which CI environments don’t persist).

❌ It needs special setup for credentials and Git configuration.

❌ It requires --init-history the first time you push a new branch — and only the first time.

---

Summary

Copybara offers a powerful, flexible way to control how code moves between repositories. While more complex than plain git, it allows full control over filtering, authoring, and commit structure.

It works best when:

• You need to filter out sensitive files
• You want to preserve authorship
• You want to define repeatable sync logic

We use it to mirror internal development to our public forks while maintaining clean, auditable, and collaborative histories.

[AlexanderLanin]

Moved to https://github.com/eclipse-score/score/blob/fork/docs/contribute/fork/index.md to make working on it easier