Add VCS module publish command by AadarshIBM · Pull Request #105 · hashicorp/tfctl-cli

AadarshIBM · 2026-08-24T19:46:22Z

Description

Adds tfctl module publish for publishing VCS private registry modules from existing OAuth or GitHub App connections.

The command:

Requires a repository and exactly one VCS connection ID.
Uses tag-based publishing by default.
Supports branch-based publishing with an optional initial version.
Resolves the organization from the explicit flag, active profile, or Terraform configuration.
Supports JSON, Markdown, dry-run, and quiet behavior.
Uses tfctl's existing authenticated client because go-tfe/v2 does not yet provide a method for this endpoint.
Returns immediately without polling and reports the API status verbatim.
Restricts output and logs to safe module metadata.

For repositories that follow the standard terraform-<provider>-<name> naming convention, HCP Terraform automatically determines the module name and provider. Custom name/provider overrides and repositories requiring different VCS identifier and display-identifier values are outside this initial scope and can use tfctl api.

Validation completed:

go test ./internal/commands/module ./internal/commands/root -count=1
make gen/screenshot
make bin
make check
go test ./... -race
git diff --check

Example Output

Tag-based publishing dry run:

$ tfctl module publish \
    --repo acme/terraform-aws-network \
    --oauth-token-id ot-... \
    --organization acme \
    --dry-run

DRY RUN: would publish VCS-backed module from repository "acme/terraform-aws-network" to organization "acme" using tag-based publishing

Branch-based publishing:

$ tfctl module publish \
    --repo acme/terraform-aws-network \
    --github-app-installation-id ghain-... \
    --branch main \
    --initial-version 1.0.0

PR Checklist

Prepared a changelog entry for the next set of release notes.
Ensured the command is sensitive to these global flags:
- --json — Forces machine-readable output to stdout.
- --markdown — Forces Markdown output to stdout.
- --dry-run — Resolves and validates the request without sending a mutation.
- --quiet — Suppresses successful output and unessential guidance.
Added safe debug logging using the logger from the command context.
Regenerated the root command screenshot with make gen/screenshot.
Reviewed autocomplete behavior. Repository, connection, branch, and version values do not have reliable local autocomplete, so autocomplete is not provided for them.

PCI review checklist

I have documented a clear reason for, and description of, the change I am making.
Reverting this pull request fully removes the command. There are no migrations or persisted local state changes.
This change does not modify security controls. Request bodies and VCS connection IDs are not included in command output or logs.

paladin-devops

I have some pretty minor feedback, great job adding this command!

paladin-devops · 2026-08-25T18:11:22Z

+		ShortHelp: "Manage private registry modules.",
+		LongHelp: heredoc.New(inv.IO).Mustf(`
+		The {{ template "mdCodeOrBold" "%s module" }} command group lets you manage
+		private registry modules in HCP Terraform and Terraform Enterprise.
+		`, version.Name),


Good description and short help text. 👍🏻

paladin-devops · 2026-08-25T18:48:09Z

+	if opts.Quiet {
+		logger.Debug("Quiet mode enabled, rendering skipped")
+		return nil
+	}
+


We should drain the body before returning here. This way, if the server were to have keep-alives enabled, then the TCP connection could be returned to the connection pool, instead of being closed, which is the default behavior of Go's HTTP implementation for undrained response body.

Suggested change

if opts.Quiet {

logger.Debug("Quiet mode enabled, rendering skipped")

return nil

}

if opts.Quiet {

logger.Debug("Quiet mode enabled, rendering skipped")

io.Copy(io.Discard, resp.Body)

return nil

}

paladin-devops · 2026-08-25T18:57:19Z

@@ -0,0 +1,3 @@
+kind: ENHANCEMENTS
+body: "Added `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections"


nit: Present-tense changelog note.

Suggested change

body: "Added `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections"

body: "tfctl now has `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections."

paladin-devops · 2026-08-25T20:01:31Z

+	if response.Data.Links.Self != "" {
+		result.SelfLink, err = resolvePublishSelfLink(opts.Client.BaseURL, response.Data.Links.Self)
+		if err != nil {
+			return fmt.Errorf("failed to resolve registry module self link: %w", err)


We should add a test to publish_test.go for this error case.

paladin-devops · 2026-08-25T20:15:24Z

+	return fields
+}
+
+func resolvePublishSelfLink(base *url.URL, self string) (string, error) {


I think that we could add some tests to publish_test.go, maybe in a new function TestResolvePublishSelfLink, which just tests this function's paths, rather than doing so implicitly via TestRunPublishOutputFormats.

paladin-devops · 2026-08-25T20:17:03Z

+			})
+		},
+	})
+	opts.Quiet = true


Does Quiet need to be true for this test?

brandonc

Hoping to have a conversation about a potential --provider argument and a couple of usability ideas. Everything looks great

brandonc · 2026-08-28T15:25:33Z

+		LongHelp: heredoc.New(inv.IO, heredoc.WithPreserveNewlines()).Mustf(`
+		The {{ template "mdCodeOrBold" "%s module publish" }} command publishes a private registry module from an existing VCS connection.
+
+		Provide exactly one of {{ template "mdCodeOrBold" "--oauth-token-id" }} or {{ template "mdCodeOrBold" "--github-app-installation-id" }}.


What would you say is the best way to identify the token ID that you should use for this command? I used the api command to navigate around this area but I'm wondering if there could be usability gains by supporting a service-provider or oauth client name.

Imagine:

$ tfctl module publish brandonc/terraform-aws-bootstrap --provider github

If "github" could be used to disambiguate the list of available providers, matching only one, you could then navigate to whichever token we show on the VCS providers screen.

Fallback option:

$ tfctl module publish brandonc/terraform-aws-bootstrap --oauth-token-id ot-...

I've also discovered that it's not possible to discover the github app installation ID because that endpoint requires cookie authentication. Can we provide some guidance about how to get the --github-app-installation-id?

brandonc · 2026-08-28T16:21:31Z

+	return nil
+}
+
+type publishRequestEnvelope struct {


I'd love if you could provide some comments here about how these types (and the call to client.Do) are a substitute for missing OpenAPI definition -- it could be migrated to a native Client API call eventually and I don't want to lose sight of that.

brandonc · 2026-08-28T16:35:53Z

+	}
+
+	if opts.Quiet {
+		logger.Debug("Quiet mode enabled, rendering skipped")


It's humorous because this can never be logged by tfctl but I like the completeness. Some day there may be a file log or something.

brandonc · 2026-08-28T16:40:18Z

+	logger.Debug("Publishing VCS-backed registry module",
+		"method", http.MethodPost,
+		"path", requestURL.Path,
+		"organization", organization,
+		"mode", publishingMode,
+	)


FYI the method and path are debug logged by the API Client:

10:28:00.836 [DEBUG] tfctl.module publish: Publishing VCS-backed registry module: method=POST path=/api/v2/organizations/bcroft/registry-modules/vcs organization=bcroft mode=branch-based 10:28:00.836 [DEBUG] tfctl.module publish: HTTP request: method=POST url=https://app.staging.terraform.io/api/v2/organizations/bcroft/registry-modules/vcs

brandonc · 2026-08-28T16:44:45Z

+	Namespace string `json:"namespace,omitempty"`
+	Provider  string `json:"provider,omitempty"`
+	Status    string `json:"status,omitempty"`
+	SelfLink  string `json:"self_link,omitempty"`


I thought it might be useful to add an html_link here if you can derive it from the response so I can ctrl-click and navigate to it after the command runs.

/app/bcroft/registry/modules/private/ORGANIZATION/NAME/PROVIDER and let the server redirect to the version or show the status

While pending, the UI shows:

Waiting for module MODULENAME to become ready… This page will automatically refresh.

Add VCS module publish command

812ec36

paladin-devops reviewed Aug 25, 2026

View reviewed changes

brandonc reviewed Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add VCS module publish command - #105

Add VCS module publish command#105
AadarshIBM wants to merge 1 commit into
hashicorp:mainfrom
AadarshIBM:module-publish

AadarshIBM commented Aug 24, 2026 •

edited

Loading

Uh oh!

paladin-devops left a comment

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

paladin-devops Aug 25, 2026

Uh oh!

brandonc left a comment

Uh oh!

brandonc Aug 28, 2026

Uh oh!

brandonc Aug 28, 2026 •

edited

Loading

Uh oh!

brandonc Aug 28, 2026

Uh oh!

brandonc Aug 28, 2026

Uh oh!

brandonc Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,3 @@
		kind: ENHANCEMENTS
		body: "Added `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections"

	body: "Added `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections"
	body: "tfctl now has `tfctl module publish` for publishing VCS-backed private registry modules from existing OAuth or GitHub App connections."

Uh oh!

Conversation

AadarshIBM commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example Output

PR Checklist

PCI review checklist

Uh oh!

paladin-devops left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandonc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandonc Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AadarshIBM commented Aug 24, 2026 •

edited

Loading

brandonc Aug 28, 2026 •

edited

Loading