Synopsis

mod-connect github [--verbose] [--accessToken=<accessToken>] [--additionalBuildArgs=<additionalBuildArgs>] [--apiUrl=<apiURL>] [--branch=<branch>] [--cliVersion=<cliVersion>] [--dispatchSecretName=<dispatchSecretName>] [--javaVersion=<javaVersion>] --publishPwdSecretName=<publishPwdSecretName> --publishUrl=<publishUrl> --publishUserSecretName=<publishUserSecretName> [--repo=<repository>] [--repoReadSecretName=<repoReadSecretName>] (--path=<path> | --fromCsv=<csvFile>)

Description

This command will create a GitHub workflow that builds and publishes LST artifacts to your artifact repository on a regular basis. A workflow can be created for ingesting a single repository (by specifying the path parameter) or a workflow can be created for ingesting a mass number of repositories (by specifying the fromCsv parameter).

If you specify the path parameter:

This command will create a moderne-workflow.yml file in the .github/workflows directory at the path you specified. This workflow file can then be modified and published to a GitHub repository to set up the workflow for building and publishing LST artifacts for that repository.

When running this command, you will need to ensure that you provide the publishPwdSecretName, publishUrl, and publishUserSecretName parameters.

For the publishPwdSecretName and publishUserSecretName parameters, the expectation is that you will create a GitHub secret for each inside of the repository you’re wanting to ingest. When running this command, you’d then provide the names of these secrets rather than the secrets themselves (e.g., --publishPwdSecretName <name of GitHub secret>).

  • Example:

    mod connect github --publishPwdSecretName publishPwdSecretName \
    --publishUrl https://some-repo.com \
    --publishUserSecretName publishUserSecretName \
    --path /path/to/project

If you specify the fromCsv parameter:

This command will directly commit an ingestion workflow and the necessary files to run it to the GitHub repository you specify. This workflow will iterate over every repository in the CSV and build/publish LST artifacts for each.

Before running this command, you will need to ensure that you’ve created a dedicated GitHub repository where all of these files can be uploaded to.

When running this command, you will need to ensure that you provide the accessToken, dispatchSecretName, publishPwdSecretName, publishUrl, publishUserSecretName, repo, and repoReadSecretName parameters.

For the dispatchSecretName, repoReadSecretName, publishPwdSecretName and publishUserSecretName parameters, the expectation is that you will create a GitHub secret for each inside of the repository you provided to this command. When running this command, you’d then provide the names of these secrets rather than the secrets themselves (e.g., --publishPwdSecretName <name of GitHub secret>).

  • Example:

    mod connect github --accessToken moderne-github-access-token \
    --dispatchSecretName dispatchSecretName \
    --fromCsv /path/to/repos.csv \
    --publishPwdSecretName publishPwdSecretName \
    --publishUrl https://artifact-place.com/artifactory/moderne-ingest \
    --publishUserSecretName publishUserSecretName
    --repo company-name/repo-name \
    --repoReadSecretName readSecretName

Options

--accessToken=<accessToken>

A classic GitHub access token that will be used to commit files and create workflows (a fine-grained token won’t work). This token will not be used to run the workflows.

This token requires the workflow permission.

This parameter is required if the fromCSV parameter is specified.

--additionalBuildArgs=<additionalBuildArgs>

Additional arguments that are added to the Maven or Gradle build command.

Example: -Dmaven.antrun.skip=true

--apiUrl=<apiURL>

The base URL for the GitHub REST API. For GitHub enterprise users, this commonly follows the format of: http(s)://HOSTNAME/api/v3

Default: https://api.github.com

--branch=<branch>

The branch of the repository specified in the repo parameter where the generated workflow files should be committed to.

Default: main

--cliVersion=<cliVersion>

The version of the Moderne CLI that should be used when running the ingestion workflow. Follows standard semantic versioning with a v in front.

Example: v2.0.5

--dispatchSecretName=<dispatchSecretName>

The name of the GitHub secret that contains the access token that will be used to run the GitHub workflows in the repo specified in the repo parameter.

This token requires the workflow permission.

GitHub secrets can be created inside of of the Security → Secrets → Actions section in a GitHub repository.

This parameter is required if the fromCSV parameter is specified.

--fromCsv=<csvFile>

The location of the CSV file containing the list of repositories that should be ingested into Moderne. A GitHub action will build and publish LST artifacts for every repository in this file.

Follows the schema of:

[repoName,repoBranch,javaVersion,desiredStyle,additionalBuildArgs,skip,skipReason]

  • repoName: Required - The repository that should be ingested. Follows the format of organization/repository.

    • Example: openrewrite/rewrite

  • repoBranch: Optional - The branch of the above repository that should be ingested.

    • Default: main

  • javaVersion: Optional - The Java version used to compile this repository.

    • Default: 11

  • desiredStyle: Optional - The OpenRewrite style name to apply during ingest.

    • Example: org.openrewrite.java.SpringFormat

  • additionalBuildArgs: Optional - Additional arguments that are added to the Maven or Gradle build command.

    • Example: -Dmaven.antrun.skip=true

  • skip: Optional - If set to true, this repo will not be ingested.

    • Default: false

  • skipReason: Optional - The context for why the repo is being skipped.

    CSV Example:

    openrewrite/rewrite-spring,main,11,org.openrewrite.java.SpringFormat,,false,,
    openrewrite/rewrite,master,17,,-Phadoop_2,,
    foo/bar,main,11,,,true,some skip reason
    // More Rows

    To run the connect github command, you must either specify the path or the fromCsv parameter.

--javaVersion=<javaVersion>

The Java version needed to compile and run the repository that is indicated in the path parameter. Can be any major version (e.g., 8, 11, 17).

Default: 11

--path=<path>

The local path to the Git repository where a GitHub workflow should be created.

To run the connect github command, you must either specify the path or the fromCsv parameter.

--publishPwdSecretName=<publishPwdSecretName>

The name of the GitHub secret that contains the password needed to upload LST artifacts to your artifact repository.

GitHub secrets can be created inside of of the Security → Secrets → Actions section in a GitHub repository.

--publishUrl=<publishUrl>

The URL of the Maven formatted artifact repository where LST artifacts should be uploaded to.

Will default to the environment variable MODERNE_PUBLISH_URL if one exists.

--publishUserSecretName=<publishUserSecretName>

The name of the GitHub secret that contains the username needed to upload LST artifacts to your artifact repository.

GitHub secrets can be created inside of of the Security → Secrets → Actions section in a GitHub repository.

--repo=<repository>

The dedicated GitHub repository where the workflows and the CSV file will be committed to. Follows the format of organization/repository name.

This parameter is required if the fromCSV parameter is specified.

Example: openrewrite/rewrite

--repoReadSecretName=<repoReadSecretName>

The name of the GitHub secret that contains the access token with read access to each repository in the provided CSV.

GitHub secrets can be created inside of of the Security → Secrets → Actions section in a GitHub repository.

This parameter is required if the fromCSV parameter is specified.

--verbose

If enabled, additional debug statements will be printed throughout the GitHub configuration.

Default: false