Skip to main content

Configure Organizations with Moderne DX

Many users desire the ability to dynamically control the organizational structure (repository groupings) of their repositories within Moderne DX. There are two ways to achieve this, either by supplying DX with a file describing the organizational structure (via a repos.csv) or by integrating with an organization service.

In order for Moderne to obtain information about your organizational structure, you will need to configure the Moderne DX service to point to your Organizations source. This guide will explain how to do that.

Prerequisites​

This guide assumes that:

File based organization structure​

The simplest way to achieve the organization structure is to supply a repos.csv file directly in DX.

That being said, there are a few downsides of file based organization structure:

  • You cannot configure any DevCenter
  • Organization based access control is not available

Generating repos.csv​

If you choose to fork our Organizations service template, you will have to generate your repos.csv file. This file takes the following format:

cloneUrlbranchorg1org2org3
https://github.com/openrewrite/rewrite-recipe-bommainOpen SourceALL
https://github.com/Netflix/spectator-gomainNetflixOpen SourceALL

The organizations under org1, org2, org3, etc. represent the hierarchy of organizations. There is no limit to the number of organizations that can be provided via this CSV.

The above example would be used in Moderne DX to generate an organizational listing of the following:

  • ALL
    • Open Source
      • https://github.com/openrewrite/rewrite-recipe-bom:main
    • Netflix
      • https://github.com/Netflix/spectator-go:main

To generate this repos.csv, we recommend using "repo fetchers".

Service based organization structure​

A more feature rich replacement of the file based approach is to create an Organizations service. This allows you to use additional features like the DevCenter, organization based access control, and per organization commit options.

Organizations service template and API​

You have two main options for building this service. You can:

  1. (Recommended) Fork our Organizations service template and modify it to meet your needs. Please see the README for how to spin this up quickly. It can be as simple as updating a CSV file.
  2. Build your own service that fulfills the GraphQL contract using any GraphQL stack (e.g., NodeJS, Rust, C#, etc.)

We generally recommend forking the template and modifying it as, in most cases, that will be faster and easier than building it yourself. Regardless of which one you choose, however, some developer time will be required on your end.

Deploying the service​

How you deploy the service is largely up to your company. With that being said, there are a few important things to be aware of:

  • Moderne will make a request per repository to the Organizations service once every 10 minutes by default (you can change this interval in your configuration). Please ensure that you have metrics to track how this service is performing so you can adjust it over time.
  • You'll want a minimum system spec of 2 CPU cores, 8 GB of memory, and at least 10 GB of persistent storage.

DX organization structure configuration​

The following table contains all of the variables/arguments you need to add to your Moderne DX service run command in order for it to interact with your organization structure data source. Please note that these variables/arguments must be combined with ones found in other steps in the Configuring the Moderne DX service guide.

Variables:

Variable NameRequiredDefaultDescription
MODERNE_DX_ORGANIZATION_URLtrueThe URL of your GraphQL service that provides organization information. Cannot be combined with MODERNE_DX_ORGANIZATION_REPOSCSV.
MODERNE_DX_ORGANIZATION_REPOSCSVtrueThe path of your repos.csv file that provides organization information. Cannot be combined with MODERNE_DX_ORGANIZATION_URL.
MODERNE_DX_ORGANIZATION_DEFAULTCOMMITOPTIONSfalseThe commit options used if not specified by the organization service.
MODERNE_DX_ORGANIZATION_UPDATE_INTERVAL_SECONDSfalse600Specifies how often to request your organization information. Only used when combined with MODERNE_DX_ORGANIZATION_URL.
MODERNE_DX_ORGANIZATION_SKIPSSLfalsefalseSpecifies whether or not to skip SSL validation for HTTP connections to this Organization service instance. Only used when combined with MODERNE_DX_ORGANIZATION_URL. This must be set to true if you use a self-signed SSL/TLS certificate.

Example:

docker run \
# ... Existing variables
-e MODERNE_DX_ORGANIZATION_URL=http://localhost:8091 \
-e MODERNE_DX_ORGANIZATION_UPDATE_INTERVAL_SECONDS=600 \
-e MODERNE_DX_ORGANIZATION_DEFAULTCOMMITOPTIONS=Direct,Branch,Fork,PullRequest,ForkAndPullRequest \
# ... Additional variables

Confirming it works​

After starting up Moderne DX again, you can now make the following GraphQL query using the embedded GraphiQL IDE found at https://<moderne-dx-host>:8080/graphiql:

query orgs {
  organizations {
    id
    repositoriesPages {
      count
      edges {
        node {
          origin
          path
          branch
        }
      }
    }
    parent {
      id
    }
  }
}

If you run this immediately after startup, you may get no results. Once your index operation is completed, you will get results similar to the following:

{
  "data": {
    "organizations": [
      {
        "id": "Organization 1",
        "repositoriesPages": {
          "count": 2,
          "edges": [
            {
              "node": {
                "origin": "github.com",
                "path": "organization/repository1",
                "branch": "main"
              }
            },
            {
              "node": {
                "origin": "github.com",
                "path": "organization/repository2",
                "branch": "main"
              }
            }
          ]
      },
      {
        "id": "Organization 2",
        "repositoriesPages": {
          "count": 7,
          "edges": [...]
        }
      },
      {
        "id": "Organization 3",
        "repositoriesPages": {
          "count": 25,
          "edges": [...]
        }
      }
    ]
  }
}

Using Moderne DX with organizations​

Once you've configured all of the above things, you can use the Moderne CLI (mod) and run the following commands:

This command will set your Moderne location to your internally-deployed Moderne DX installation:

mod config moderne edit --token=<token> --api=https://<moderne-dx-host>:8080 http://<moderne-dx-host>:8080

This command will ask Moderne DX for all repositories inside the organization you selected and clone them to <path>:

mod git clone moderne <path> <organization-id>

Once these are both done, your developers can now start running recipes and committing the results!