Important

This command can only be used by users with the DevOps role.

custom-modules

The stackgen upload custom-modules command allows your DevOps users to upload custom modules via Public or Private repositories. The scope of the custom module created via this method will be set to Enterprise level which means, it can be accessed across all projects within StackGen.

Supported Clouds

All cloud providers.

Usage

stackgen upload custom-modules [flags]

Aliases: custom-modules, custom-resources

Example

stackgen upload custom-modules .

This command uploads custom modules from the current directory (.) to StackGen. The uploaded module is then available to all projects in the organization.

Flags

Flag	Type	Description
--branch	string	Branch from which the custom module are to be read.
-h, --help		Help for custom-modules.
--name	string	Unique identifier (name) for the custom module. Only alphanumeric characters, hyphens -, and underscores _ are allowed.
--overwrite-version		Overwrite existing custom module version if it exists.
-p, --provider	string	Provider for the custom module. The default value is aws.
--repo-url	string	Repository URL for the custom module.
-t, --secret-name	string	Secret name (created in secret store) for repository authentication in case of private repository. If not provided, will read token from SCM_TOKEN and SCM_TYPE (github, gitlab, azurescm, bitbucket) env variable and create ephemeral secret in StackGen for uploading the module. If the env variable is not provided, it will assume that it is a public repository.
-d, --subdir	string	Subdirectory in the repository to scan for module.
--tag	string	Tag value of the repository for the custom module.
--version	string	Version name for the custom module. The default value is 1.0.

You can upload a custom module using the --repo-url flag.

• Public repository: If you do not set --secret-name and do not set SCM_TOKEN or SCM_TYPE, CLI will assume that you are uploading the custom module from a public repository.
• Private repository: you must provide authentication.

Upload from a public repository

Click to view

Do not set --secret-name and do not set SCM_TOKEN or SCM_TYPE. The CLI will assume that you are uploading the custom module from a public repository.

stackgen upload custom-modules \ 
--tag version tag of the repo \
--repo-url "public repo url" \
--name "module name"

Optional: use --branch, --tag, and -d or --subdir to specify the branch, tag, or subdirectory from where the CLI has to read the custom module.

Upload from a private repository

Click to view

You must authenticate using one of the following:

Option 1: Secret from StackGen secret store

Create a secret in StackGen secret store (Settings > Secret Store) for your SCM provider. Pass the name of your secret using the -t, --secret-name flag:

stackgen upload custom-modules \
--branch branchname, eg main \
--repo-url "url of private repo" \
--name "name of module" \
--subdir "sub directory of the repo" \
--secret-name "your secret name" created in secret store \

Option 2: Environment variables

Set SCM_TOKEN and SCM_TYPE in your shell (or in your CI/CD pipeline’s environment) before running the command. Use SCM_TYPE for your provider (github, gitlab, azurescm, or bitbucket). The CLI will create an ephemeral secret in StackGen for the upload:

export SCM_TOKEN="your_token"
export SCM_TYPE="github"

stackgen upload custom-modules . \
--repo-url repo url \
-p provider \
--name module name \
--version module version

When running in a supported SCM pipeline (e.g. GitHub Actions), the pipeline’s token (e.g. GITHUB_TOKEN) is often available automatically; see your pipeline’s documentation.

note

GitHub Enterprise: You may need to allowlist StackGen’s egress IP addresses in your corporate firewall. Contact your StackGen representative for the list.

Sample File Format for a Custom Module

Click to view

The custom modules file should be in JSON format and define the structure and properties of your custom modules. Here's a simplified example:

{
  "resources": [
    {
      "type": "custom_database_cluster",
      "provider": "aws",
      "schema": {
        "required": ["cluster_size", "engine_version"],
        "properties": {
          "cluster_size": {
            "type": "integer",
            "description": "Number of nodes in the cluster"
          },
          "engine_version": {
            "type": "string",
            "description": "Database engine version"
          },
          "backup_retention_days": {
            "type": "integer",
            "default": 7,
            "description": "Number of days to retain backups"
          }
        }
      }
    }
  ]
}

note

• Custom modules can fill gaps in the standard resource library.
• Ensure your custom resource definitions follow the required schema format.
• You can reference existing resources as dependencies in your custom modules.