Skip to main content

Organization source migration

In order to simplify Moderne's operational complexity, we decided that configuring organizational hierarchies should only require creating a file and giving it to the Moderne agent (either via direct access or via an unauthenticated HTTP/S endpoint), rather than running a dedicated endpoint for organization hierarchy via an Organizations service.

While you can still run an Organizations service to restrict access to various repositories/organizations or to customize commit messages by repository, the functionality around org hierarchies is being moved to the Agent.

This guide will walk you through everything you need to know to migrate this functionality to the Moderne Agent.

Migration instructions

At a high-level, the migration process is as follows:

  1. Remove any outdated configuration related to the org hierarchies or DevCenters from your Agent
  2. Configure the Agent to use repos.csv and devcenter.json
    • If copying from a previous repos.csv file, you may need to make some minor changes to your repos.csv file.
  3. Ensure that your agent is using at least version 0.221.0 (to get the latest variable names included in this doc)
  4. (Optionally) If you don't plan on using an Organizations service anymore, remove it from your system.

1. Remove any old configuration variables from your Agent

Make sure that the following configurations are not included in your Agent run command:

Variables:

Argument Name
MODERNE_AGENT_ORGANIZATION_FILE_REPOSCSVPATH
MODERNE_AGENT_ORGANIZATION_FILE_COMMITOPTIONSPATH
MODERNE_AGENT_ORGANIZATION_FILE_IDMAPPINGPATH
MODERNE_AGENT_ORGANIZATION_FILE_DEVCENTERPATH
MODERNE_AGENT_ORGANIZATION_SERVICE_UPDATEINTERVALSECONDS

2. Create the new files and put them somewhere the Agent can access

  1. Copy the devcenter.json file from your Organization service and put it somewhere where your Agent can access. This could mean putting this file on the same file system that Agent has access to – or it could mean putting it behind an unauthenticated HTTP/S endpoint.
  2. Follow our guide for creating a repos.csv file. Alternatively, if your Organization service already uses a repos.csv, you may copy that file directly and put it somewhere where your Agent can access (either by putting it on a file system the agent has access to or by putting the file behind an unauthenticated HTTP/S endpoint that the agent can call).

3. Configure the Agent to use the new variables

Update the relevant variables in your Agent deployment so that your Agent knows where these files are.

Environment Variables:

Environment VariableDefaultDescription
MODERNE_AGENT_ORGANIZATION_REPOSCSVThe path of your repos.csv file that provides organization information. This could also be an unauthenticated HTTP/S URL in the form of https://<internal-endpoint>/repos.csv.
MODERNE_AGENT_ORGANIZATION_DEVCENTERThe path of your devcenter.json file that provides the DevCenter configurations. This could also be an unauthenticated HTTP/S URL in the form of https://<internal-endpoint>/devcenter.json.
MODERNE_AGENT_DEFAULTCOMMITOPTIONS_{index}falseUse to restrict which commit options are available in Moderne. Acceptable values: Direct, Branch, Fork, PullRequest, ForkAndPullRequest. Defaults to allowing access to all commit options.
MODERNE_AGENT_ORGANIZATION_UPDATEINTERVALSECONDS600Specifies how often to request your organization information.

Example:

docker run \
# ... Existing variables
-e MODERNE_AGENT_ORGANIZATION_REPOSCSV=/Users/MY_USER/Documents/repos.csv \
-e MODERNE_AGENT_ORGANIZATION_DEVCENTER=/Users/MY_USER/Documents/devcenter.json \
-e MODERNE_AGENT_DEFAULTCOMMITOPTIONS_0=PullRequest \
-e MODERNE_AGENT_DEFAULTCOMMITOPTIONS_1=ForkAndPullRequest \
-e MODERNE_AGENT_ORGANIZATION_UPDATEINTERVALSECONDS=600 \
# ... Additional variables

Notable changes from the previous Organization Service

Organization ID changes

It's no longer possible to customize ID names via an id-mapping.txt file. Organization IDs are, instead, entirely generated from the organization names. For instance, if you have a repos.csv file that looks like this:

cloneUrl,branch,org1,org2,org3,org4
<url>,<branch>,Team,Director,VP,ALL

Then four organizations will be produced. The IDs for these organizations will be:

  1. ALL/VP/Director/Team
  2. ALL/VP/Director
  3. ALL/VP
  4. ALL

These are the IDs you'd then use in your devcenter.json file if you wanted to create DevCenters. These are also the IDs you can use with the CLI when you run commands like: mod git clone moderne <path> <moderne org id>.

Note that above command also allows you to clone orgs with just the name instead of the ID – but if multiple organizations share the same name it will then ask you to pick which one you want.

Commit option changes

It's no longer possible to define commit options on a per-org basis. Instead, you must define what commit options you want available in your agent and those commit options will be shared between all organizations.