Skip to main content

How to create and configure an organizational structure to group repositories

Many organizations desire the ability to dynamically control the organizational structure (repository groupings) of their repositories within the Moderne Platform. To facilitate this need, Moderne offers two options: integration with an Organizations service that is hosted in your environment or a simpler, file-based system.

Let's walk through everything you need to know about both of these options.

Which to pick?​

While both options offer you the ability to control an organizational structure, there are advantages/disadvantages to each.

Running an Organization service allows for more flexibility when setting up the required GraphQL and REST endpoint. For instance, you can configure custom commit messages, so you can automate tasks like adding a JIRA ticket to a commit message. On the other hand, providing the agent with the files requires less setup at the cost of limited flexibility. It's much quicker and simpler to get started.

Because of that, we'd recommend the file-based approach unless you have a compelling reason to not do that.

tip

When selecting which option is best for you, keep in mind that you can change the approach you have taken later.

To configure an organizational structure with files, you will need to:

  1. Review the list of potential files which can be provided on the agent.
  2. Determine which files your setup requires – and then create those.
  3. Place the files somewhere your agent has access to.
  4. Update your agent configuration to point to the files.

Running an Organization service​

To configure an organization structure with a dedicated service, you will need to:

  1. Create and deploy an Organizations service that fulfills this GraphQL contract and this REST contract your environment._
  2. Configure your Moderne agent to point to this service.

Coding the Organizations service​

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 JSON file that you get from the Moderne Platform.
  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:

  • Communication with the Organizations service is done through the Moderne agent. Therefore, this service must be accessible from the agent.
  • Moderne will make a request per repository to the Organizations service once every 10 minutes by default (you can change this interval in your agent 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.

Configuring custom commit messages​

By default, when a user creates a commit in the Moderne Platform, the commit message they provide is the one that is used. However, there are some instances where you may not want this. For example, maybe you want to apply a transformation to the existing message to retrieve a JIRA ticket and add it into the commit message.

To do this, you will need to add custom logic to the commitMessage query. This query expects a message and an extendedMessage. If this commit will be used to create a PR, the message will be the title of the PR and the body will be the extendedMessage.

For example, if your message is: Purr-fect fix: Cat avatars now display correctly and your extendedMessage is: Resolved issue where cat avatars were displaying upside down. – then your commit will look like:

Purr-fect fix: Cat avatars now display correctly

Resolved issue where cat avatars were displaying upside down.

Organizations service FAQ​

If the Organizations service stops responding (e.g., the service is down), what is the expected behavior?​

The organizations a user can see in the Moderne Platform are determined by the userOrganizations query. If the service is down, then organizations and repositories will be unavailable and recipes would, therefore, be unable to run.

How do you restrict which commit options are available in the UI?​

You can change this in the commitOptions array in your organizations service. See the configuration options on our reference implementation.

What would happen if the service returned an empty commitOptions array? Would that disable commit capabilities for these organizations?​

Violating the GraphQL contract will cause errors and make it so the Moderne Platform will not function as expected. Since the GraphQL contract expects commitOptions to be populated, the query will error if no options are returned. In turn, users won't be able to run recipes.

If no Organizations service is active/configured, would it be possible to change the default commit options and repositories in the Moderne UI?​

No – it is not possible to change the defaults. If no Organizations service is configured in the agent, then an All organization will be returned that contains all of the repositories in your org. If an Organizations service is configured – but not accessible – then nothing will be available in Moderne.

How often are organizations synced to Moderne?​

By default, organizational data is synced every 10 minutes. You can increase or decrease this by modifying your agent configuration.

Is it possible to manually force a sync of the organizations?​

Yes. There is a GraphQL admin-only mutation to force a refresh on demand (refreshOrganizations).

What does a query to this service look like?​

curl --request POST \
  --url https://organizations.company-name.com/graphql \
  --header 'Content-Type: application/json' \
  --data '{"query":"query orgs($repository: RepositoryInput) {\n\torganizations(repository: $repository) {\n\t\tid\n\t\tname\n\t\tcommitOptions\n\t}\n}","operationName":"orgs","variables":{"repository":{"origin":"github.com","path":"Netflix/curator","branch":"master"}}}'

Do you have an architecture diagram that shows where this service fits in?​

Yes - see our architecture documentation.