---
# System prepended metadata

title: ForgeFlux

---

# ForgeFlux

[ForgeFlux](https://forgeflux.org/) aims to implement federation in [software forges](https://en.wikipedia.org/wiki/Forge_(software)), enabling
a decentralized development environment.

## Why is this significant?

Free software developers are asked to choose between freedom and having
access to a large community while choosing a software forge.\
This has resulted in various forge spaces for projects being set up
according to the comfort/preference of the developer community centered
around the project.

While this is great for the developer base which is invested in the
project, the exposure that is provided to the project falls
significantly short.\
The initial [forgefed](https://forgefed.peers.community/) was an
attempt to bridge this gap, by introducing the concept of bridging the
gap between forges.\
This approach required for the forge developers to actively participate
in the development of the software.


With ForgeFlux, we are trying to implement federation external to the forge, entirely using the forge’s API. Our approach involves implementing adapter-like software, called Interfaces, that interact with the forge’s API and speak a common protocol.

ForgeFlux, consists of a terminology for the development and
utilization of it\'s software, which result in terms such as
`forges`, and `interfaces` being tossed around.\
It is recommended for a reader to go through the
[ecosystem-architecture](https://github.com/forgeflux-org/spec/blob/master/rfc/1-ecosystem-architecture/1-ecosystem-architecture.md),
if there is any confusion regarding the usage of particular words in
this documentation.

## Features

### Forge Independence

The services that Forge Flux seeks to provide aims to keep progression
of a project, and the forge on separate terms, ensuring that a user\'s
preference for a forge does not dictate their dedication towards the
project.

## Getting Started

### How does it work?

Interfaces are services that are run on the side of any user, and are
used as connecting points of the bridge.\
These interfaces are responsible for communicating with each other, and
interact in the form of messages for a server-server model, and a REST
API model for the server-user model.

Interfaces are geared towards performing various operations for the
repository, which include but are not limited to,

-   Pull Requests
-   Issues
-   Comments
-   Notifications
-   Forking

However, as the count for interfaces go up in magnitudes, it becomes
increasingly hard to keep track of them.\
This is where Northstar comes to play, by implementing a lookup server
that seeks to provide an indexed list of available forge interfaces.

ForgeFlux is currently in the Active Development phase, and is being
worked on towards the alpha-testing stage.

### What are the services present in ForgeFlux?

1.  Northstar

    Repository
    :   <https://github.com/forgeflux-org/northstar>

    OpenAPI
    :   <https://northstar.forgeflux.org/docs/openapi/>

    ForgeFlux allows for multiple interfaces to be run against a single
    software forge.\
    Also, the protocol is flexible enough to support multiple types of
    software forges(GitLab, GitHub, etc).\
    The protocol\'s decentralised nature makes it impossible to create a
    constant record of which interfaces service forges.

    So we created a discovery service which stores records of interfaces
    and the forges they service.\
    This is very similar to the way DNS works.\
    In DNS, hostname is resolved to IP address.

    Here, software forge URL is resolved to URLs of
    [interfaces](https://github.com/forgeflux-org/interface) that
    service the queried forge.

2.  Interface

    Repository
    :   <https://github.com/forgeflux-org/interface>

    OpenAPI
    :   <https://github.com/forgeflux-org/interface/tree/master/docs/openapi>

    Developing Free Software is about liberating users and giving them
    total control over how the programs they run should work.\
    It\'s only fair that developers of such software enjoy the same
    levels of liberty.

    ForgeFlux is an attempt to enable federation for major software
    forges(GitLab, GitHub, Gitea, Source Hut, etc) entirely in
    API-space.\
    We believe our API-space implementation will allow for more organic
    growth as it will not require any involvement from the forge
    developers.

### Technical Stack & Components

1.  Northstar

    Northstar is a lookup service that allows for the ForgeFlux
    ecosystem to discover interfaces present for various forges.\
    The technology that is utilized in the case of northstar, is as
    follows,

    Flask
    :   Underlying backend for the development of the service.\

    SQLite
    :   Database for storage of the details of the various forges.

2.  Interface

    Interface is a service that can be set up by any user with an
    account in the forge and an authentication token. (Example: Personal
    Access Token in GitHub)\
    This service can be run on a local machine setting up an instance,
    which can be updated in Northstar.

    Proceeding forward, these interfaces can be located by the user in
    Northstar, through the `GET` request for forge
    interfaces. More of which is covered in the [OpenAPI
    specification](https://northstar.forgeflux.org/docs/openapi/).\
    The technology that is utilized in the case of interface are as
    follows,

    Flask
    :   Underlying backend for the development of the service.

    API Controllers
    :   The methods developed are made to utilize existing APIs present
        for the forges.

    [Libgit](https://github.com/forgeflux-org/interface/tree/master/libgit)
    :   A Rust library made for the git interface for the forgeflux
        instance.

### `Interface`: Developer Workflow

As of right now, the developer workflow for Forge Flux\'s interface and
northstar is based on the concept of [Test Driven
Development](https://en.wikipedia.org/wiki/Test-driven_development).\
None of the functionality are immediately usable, and as such, would
require you to develop tests for progress validation.

1.  Set up the development environment

    The development environment for northstar and interface, both have a
    requirement for Python, and it\'s dependencies.\
    These dependencies can be installed through a simple
    `pip install -r requirements.txt` command, however, there is a
    better alternative.

    The pre-requisites for installing the dependencies would be,

    [Python](https://wiki.python.org/moin/BeginnersGuide/Download)
    :   For the interface.

    [Rust](https://www.rust-lang.org/learn/get-started)
    :   For Libgit.

    [Virtualenv](https://virtualenv.pypa.io/en/latest/)
    :   As a Makefile cannot create a virtual environment without a
        pre-existing module for it, we will need to install virtualenv
        before we run the setup commands.

    ForgeFlux makes things easier for a development or a CI to function
    through the use of a [Makefile](https://makefiletutorial.com/).\
    So, installing dependencies for the development environment could be
    as easy as,

    ``` {.bash org-language`"sh"}
    pip install virtualenv
    virtualenv venv
    make env
    ```

    Where `make env` serves the purpose of installing all the
    dependencies required for the project.\
    The pythonic dependencies are installed via the default
    `pip` installer.

    The dependencies for the `libgit` library, are however installed by
    leveraging the features provided by the `maturin`
    package.\
    Maturin runs cargo under the hood, compiling, packaging and
    installing `libgit` into `interface`\'s virtual
    environment.

    In order to run an interface, you could simply call the following
    command,

    ``` {.bash org-language`"sh"}
    make
    ```

    However, this should only be done with a production ready model, and
    quite unfortunately, we\'re not there yet.

2.  Project Structure

The project structure for interface is segmented, and is provided as below,
```
.
├── config
├── docs
│   └── openapi
│       └── api
├── instance
├── interface
│   ├── api
│   │   └── v1
│   ├── db
│   ├── forges
│   │   ├── gitea
│   └── runner
├── libgit
│   ├── src
├── scripts
├── tests
│   ├── api
│   │   └── v1
│   ├── db
│   ├── forges
│   │   └── gitea
│   └── runner
```

The `config/` directory is used as a medium to store the user's configuration for interface, and the project implements [Dynaconf](https://www.dynaconf.com/) to handle these configurations to be utilized in the project.
The `docs/` directory is used to store all sorts of documentation for the project, and consists of the OpenAPI specification of the project as of right now.
The `instance/` directory is where the initialized database is stored for the project, which assists in abstracting all the database related operations.
The `interface/` is the Flask application, which consists of the source code components that make up the essence of the interface.
`libgit` is the Rust library that we utilize and leverage to perform git interface related tasks.
The `scripts/` directory consists of simple ease-of-life scripts that assist in coverage, spell checking, and clean up.
`tests/` is a section dedicated to the mocks that we run against the code, and is how ForgeFlux continues to be developed.

# Irrelevant notes

Works by storing the state that they require.\
Look into actor system.\
Tell the actor and get them to mutate the data, owned by a single
thread.

The sum variable is contained within an object, the only way to interact
with this object, is to send something using a queue.\
Every time you wish to add something, you just send it to the queue.

Your computation will be executed when the actor gets to it.\
The biggest problem with concurrent programming, would be to make the
same data available across threads.\
The actual data is tracked by a single thread alone.\
If you want something you ask for it.

When you send a message,\
When you use locks, you restrict it to a machine.\
You create a logical processor.