Creating a repos.csv file
Whether you are configuring mass ingestion of repositories into Moderne or you are defining an organizational hierarchy, you will need to create a repos.csv
file that defines your repositories and configuration around them.
This doc will provide you with everything you need to know about creating and using this file.
Supported columns
Column name | Required | Description | Mass ingest | Org hierarchy |
---|---|---|---|---|
cloneUrl | true | The URL of the repository that should be ingested. Example: git@github.com:google/guava.git or https://github.com/openrewrite/rewrite | ✅ | ✅ |
branch | true * | The branch of the repository that should be checked out. This column can't be used with the changeset column. Required for the agent (for Moderne Platform admins) or DX (for Moderne DX admins). Example: main | ✅ | ✅ |
changeset | false | If provided, this will check out the repository at this specific commit SHA. This column can't be used with the branch column. Example: aa5f25ac0031 | ✅ | |
gradleArgs | false | Build arguments that are added to the end of the Gradle command line when building LSTs. Example: -Dmyprop=myvalue | ✅ | |
java | false | Configures the JDK to use during LST generation. Example: 17 or 17-tem or 17.0.6-tem | ✅ | |
jvmopts | false | JVM options added to tools building LSTs. Must be configured before you can run the build command if non-standard VM options are required. Example: -Xmx4G | ✅ | |
mavenArgs | false | Build arguments are added to the end of the Maven command line when building LSTs. Example: -Pfast | ✅ | |
org* | false | If you want to configure an organizational hierarchy, you can provide one or more organization columns. Each column will specify an organization the repository should be part of. The column name should be org plus a number such as: org1,org2,org3 . There is no limit for how many orgs you can define.Example: openrewrite | ✅ |
Generating this file
To kick-start a repos.csv
file, we recommend using "repo fetchers". Repo fetchers are scripts that generate a CSV file of all of your repositories by making API calls to your source code manager.
Defining an organizational hierarchy
Org hierarchy is best explained with an example. Consider an organization that consists of two teams and two directors:
All
├── Director A
| └── Team 1
| └── Team 2
├── Director B
The following CSV file would represent this organizational structure:
cloneUrl,branch,org1,org2,org3
"https://github.com/apache/maven-doxia","master","Team 1","Director A","ALL"
"https://github.com/Netflix/photon","main","Team 2","Director A","ALL"
"https://github.com/Netflix/ribbon","master","Director A","ALL"
"https://github.com/apache/maven-doxia","master","Director B","ALL"
In the above file, we define 5 organizations (ALL, Director A, Director B, Team 1, and Team 2) and 3 repositories. Notice that one repository can be defined multiple times if you want two distinct organizations to have access to it.
Also note that organizations on the left are children of organizations on the right. For instance, Team 1
is a child of Director A
which is a child of ALL
.
Comma-separated files (CSV) are best manipulated using a dedicated editor such as Microsoft Excel, Google Sheets, or Apple Numbers. Here is what the above CSV would look like on Apple Numbers:
Formatting details
- A single row may not have more columns than what is defined in the first row.
- A single repository may be associated with multiple organizations by being referenced in multiple rows. In the above example,
maven-doxia
is associated with bothDirector B
andTeam 1
. - You can add empty orgs to the beginning, middle, or end of a row to make them line up as desired (although you don't need to).
- You can choose to surround elements with quotes or not depending on your preference – just keep in mind general CSV formatting rules.
- You can order columns in any way.
