How to specify alternative forge and mirrors?

Nowadays, it is increasingly difficult to identify the canonical forge and the available mirrors for an open source project.

How should this be expressed in publiccode.yml? In particular, is there a recommended way to distinguish between the authoritative repository and mirrors (backup)?

For example, we operate a ForgeJo instance that mirrors GitHub repositories we actively maintain. Can this relationship (canonical repository vs. mirror) be clearly and unambiguously expressed in the YAML file?

For context: url always describes the repo it is in. If the publiccode.yml file is fetched from a different place, crawlers oughta reject it as invalid, it's basically hijacking.

Mirrors would have the same requirements as url: but they can't really be checked in the same way, since the publiccode.yml is fetched from a single URL. (as a sidenote: this is related with multi-repo projects with a single publiccode.yml, that we need to find an elegant solution for: #169)

But mirrors are verifiable, can be created by anyone and there can be many of them even that we don't know about, the simplest option might be to mention official mirrors in description, as an informational note.

After all, an unofficial mirror is no different from any other clone if the hash matches. WDYT?

@bfabio

@bfabio's concern about the authority model is the right one to solve — and I think it's resolvable without changing the authority semantics of url at all. The key is that mirrors would live inside the publiccode.yml at the canonical url, not in a file hosted at the mirror. The canonical file declares its own mirrors; no mirror can declare itself. The authority chain stays intact.

Concretely:

url: https://github.com/example/project  # canonical, unchanged — file lives here

mirrors:
  - url: https://codeberg.org/example/project  # endorsed by the canonical file
  - url: https://decommissioned.example.org/owner/project
    status: deprecated

# For forge migrations: previous canonical URLs, in chronological order.
# Lets catalogs resolve stale references without manual updates everywhere.
previousUrls:
  - https://old-forge.example.org/owner/project

previousUrls handles the migration case: once a project moves forges, the new publiccode.yml at the new url declares where it used to live, letting catalogs merge stale references. Full rationale and lifecycle coverage in this proposal.

@lsmith77

We have the following use cases coming up in The Netherlands. The Dutch government is developing code.overheid.nl, in the future the gitforge for Dutch gov organisations. Right now it will serve as mirror for Github and others, but time coming it will also host its own projects.

At our registry we will scan code.overheid.nl also and now these mirrors will show up as forks (which they technically are), but it would be nice to show which "forks" are authorized mirrors.

In the future, when code.overheid.nl is more mature, projects will migrate there, so @lsmith77 's proposal is imho a good one.
@tomootes See also our own issue developer-overheid-nl/don-register-site#338

@MrSkippy

@MrSkippy we designed the following format to overcome some of the limitation https://github.com/ossbase-org/Open-Contributions-Descriptor

7. @MrSkippy we designed the following format to overcome some of the limitation https://github.com/ossbase-org/Open-Contributions-Descriptor

Thanks, this is interesting. From my read, OCD lets the public sector be transparent about how it works with open source, and it needs no adoption by the projects. That's the same placement we chose for usage and funding declarations, which organisations publish under .well-known on their own domain.

I'd like to align the two formats if you are interested.

Sure. The idea was to have an extension for the publicode.yml inside the OCD format to ensure compatibility and interoperabilty.

I remember discussing that in a presentation during a conf-call last time but it seems the people were not too much interested ;-)

I can make a proposal extension in OCD for publiccode.yml for review.

doc(spec): add the mirrors key

doc(spec): add the previousURLs key

Navigation Menu

Repository navigation

How to specify alternative forge and mirrors? #293

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

How to specify alternative forge and mirrors? #293

Description

Activity

bfabio commented on Feb 21, 2026

lsmith77 commented on May 29, 2026

MrSkippy commented on Oct 28, 2026

adulau commented on Oct 28, 2026

lsmith77 commented on Oct 29, 2026

adulau commented on Oct 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions