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

}

Thanks! Quiet mode now drains the response body before returning, while keeping the deferred close.

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.

I added a test for the malformed self-link case, it checks the error and makes sure that nothing gets printed.

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.

Thanks, I added focused tests for the different self-link cases.

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

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


Does Quiet need to be true for this test?

I kept Quiet true here to make sure API errors still show up in quiet mode. I also renamed the test to make that clearer.

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?

Furthermore, there's only ever one github-app-installation-id associated with an organization, right?

A GitHub organization/account has one Terraform Cloud App installation, but a Terraform organization can have access to installations from multiple GitHub organizations/accounts. So --provider github could still match more than one installation. For now I kept the IDs explicit and added help for finding them. I think automatic selection is better handled as a follow up.

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.

I added comments explaining why the local types and Client.Do are needed, and that we can switch to the generated client once this operation is available there.

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

Good point, I removed the duplicate method and path fields and kept the organization and publishing mode.

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.

Added this! The output now includes an optional html_link alongside self_link, using the configured Terraform host. I also added tests for HCP Terraform and TFE.

paladin-devops reviewed Aug 25, 2026

View reviewed changes

brandonc reviewed Aug 28, 2026

View reviewed changes

Add VCS module publish command

3ef7acf

AadarshIBM force-pushed the module-publish branch from 812ec36 to 3ef7acf Compare September 1, 2026 20:55

Address module publish review feedback

df26779

paladin-devops approved these changes Sep 3, 2026

View reviewed changes

AadarshIBM requested a review from brandonc September 3, 2026 17:02

		@@ -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!

AadarshIBM Sep 3, 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!

AadarshIBM Sep 3, 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!

AadarshIBM Sep 3, 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!

AadarshIBM Sep 3, 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!

brandonc 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!

AadarshIBM Sep 3, 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!

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!

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

AadarshIBM Sep 3, 2026 •

edited

Loading

AadarshIBM Sep 3, 2026 •

edited

Loading

AadarshIBM Sep 3, 2026 •

edited

Loading

AadarshIBM Sep 3, 2026 •

edited

Loading

AadarshIBM Sep 3, 2026 •

edited

Loading

brandonc Aug 28, 2026 •

edited

Loading