diff --git a/admin_organization.go b/admin_organization.go index b309898da..5c73db05c 100644 --- a/admin_organization.go +++ b/admin_organization.go @@ -72,7 +72,7 @@ type AdminOrganizationList struct { Items []*AdminOrganization } -// A list of relations to include. See available resources +// AdminOrgIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/admin/organizations.html#available-related-resources type AdminOrgIncludeOps string @@ -84,10 +84,11 @@ const ( type AdminOrganizationListOptions struct { ListOptions - // A query string used to filter organizations. + // Optional: A query string used to filter organizations. // Any organizations with a name or notification email partially matching this value will be returned. Query string `url:"q,omitempty"` - + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/docs/cloud/api/admin/organizations.html#available-related-resources Include []AdminOrgIncludeOps `url:"include,omitempty"` } @@ -117,6 +118,7 @@ func (s *adminOrganizations) List(ctx context.Context, options *AdminOrganizatio return orgl, nil } +// ListModuleConsumers lists specific organizations in the Terraform Enterprise installation that have permission to use an organization's modules. func (s *adminOrganizations) ListModuleConsumers(ctx context.Context, organization string, options *AdminOrganizationListModuleConsumersOptions) (*AdminOrganizationList, error) { if !validStringID(&organization) { return nil, ErrInvalidOrg @@ -138,6 +140,7 @@ func (s *adminOrganizations) ListModuleConsumers(ctx context.Context, organizati return orgl, nil } +// Read an organization by its name. func (s *adminOrganizations) Read(ctx context.Context, organization string) (*AdminOrganization, error) { if !validStringID(&organization) { return nil, ErrInvalidOrg @@ -158,6 +161,7 @@ func (s *adminOrganizations) Read(ctx context.Context, organization string) (*Ad return org, nil } +// Update an organization by its name. func (s *adminOrganizations) Update(ctx context.Context, organization string, options AdminOrganizationUpdateOptions) (*AdminOrganization, error) { if !validStringID(&organization) { return nil, ErrInvalidOrg @@ -178,6 +182,7 @@ func (s *adminOrganizations) Update(ctx context.Context, organization string, op return org, nil } +// UpdateModuleConsumers updates an organization to specify a list of organizations that can use modules from the sharing organization's private registry. func (s *adminOrganizations) UpdateModuleConsumers(ctx context.Context, organization string, consumerOrganizationIDs []string) error { if !validStringID(&organization) { return ErrInvalidOrg diff --git a/admin_run.go b/admin_run.go index 346dc9e58..98db74795 100644 --- a/admin_run.go +++ b/admin_run.go @@ -24,6 +24,7 @@ type AdminRuns interface { ForceCancel(ctx context.Context, runID string, options AdminRunForceCancelOptions) error } +// AdminRun represents AdminRuns interface. type AdminRun struct { ID string `jsonapi:"primary,runs"` CreatedAt time.Time `jsonapi:"attr,created-at,iso8601"` @@ -42,6 +43,7 @@ type AdminRunsList struct { Items []*AdminRun } +// AdminRunIncludeOps represents the available options for include query params. // https://www.terraform.io/cloud-docs/api-docs/admin/runs#available-related-resources type AdminRunIncludeOps string @@ -56,9 +58,11 @@ const ( type AdminRunsListOptions struct { ListOptions - RunStatus string `url:"filter[status],omitempty"` - Query string `url:"q,omitempty"` - Include []AdminRunIncludeOps `url:"include,omitempty"` + RunStatus string `url:"filter[status],omitempty"` + Query string `url:"q,omitempty"` + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/cloud-docs/api-docs/admin/runs#available-related-resources + Include []AdminRunIncludeOps `url:"include,omitempty"` } // adminRuns implements the AdminRuns interface. @@ -111,7 +115,6 @@ func (s *adminRuns) ForceCancel(ctx context.Context, runID string, options Admin return s.client.do(ctx, req, nil) } -// Check that the field RunStatus has a valid string value func (o *AdminRunsListOptions) valid() error { if o == nil { // no need to validate fields return nil diff --git a/admin_setting.go b/admin_setting.go index ccf0551fd..a3dfafb17 100644 --- a/admin_setting.go +++ b/admin_setting.go @@ -4,7 +4,6 @@ package tfe // Note that admin settings are only available in Terraform Enterprise. // // TFE API docs: https://www.terraform.io/docs/cloud/api/admin/settings.html -// AdminSettings todo type AdminSettings struct { General GeneralSettings SAML SAMLSettings diff --git a/admin_setting_cost_estimation.go b/admin_setting_cost_estimation.go index 04fa10230..e291a25f0 100644 --- a/admin_setting_cost_estimation.go +++ b/admin_setting_cost_estimation.go @@ -7,7 +7,8 @@ import ( // Compile-time proof of interface implementation. var _ CostEstimationSettings = (*adminCostEstimationSettings)(nil) -// CostEstimationSettings describes all the cost estimation admin settings. +// CostEstimationSettings describes all the cost estimation admin settings for the Admin Setting API. +// https://www.terraform.io/cloud-docs/api-docs/admin/settings type CostEstimationSettings interface { // Read returns the cost estimation settings. Read(ctx context.Context) (*AdminCostEstimationSetting, error) diff --git a/admin_setting_customization.go b/admin_setting_customization.go index d467faaa0..d429a5e99 100644 --- a/admin_setting_customization.go +++ b/admin_setting_customization.go @@ -20,7 +20,8 @@ type adminCustomizationSettings struct { client *Client } -// AdminCustomizationSetting represents the Customization settings in Terraform Enterprise. +// AdminCustomizationSetting represents the Customization settings in Terraform Enterprise for the Admin Settings API. +// https://www.terraform.io/cloud-docs/api-docs/admin/settings type AdminCustomizationSetting struct { ID string `jsonapi:"primary,customization-settings"` SupportEmail string `jsonapi:"attr,support-email-address"` diff --git a/admin_setting_general.go b/admin_setting_general.go index 5d74cd8ce..31124fd6b 100644 --- a/admin_setting_general.go +++ b/admin_setting_general.go @@ -7,7 +7,8 @@ import ( // Compile-time proof of interface implementation. var _ GeneralSettings = (*adminGeneralSettings)(nil) -// GeneralSettings describes the general admin settings. +// GeneralSettings describes the general admin settings for the Admin Setting API. +// https://www.terraform.io/cloud-docs/api-docs/admin/settings type GeneralSettings interface { // Read returns the general settings Read(ctx context.Context) (*AdminGeneralSetting, error) diff --git a/admin_setting_saml.go b/admin_setting_saml.go index 3de700faa..8ea59aed1 100644 --- a/admin_setting_saml.go +++ b/admin_setting_saml.go @@ -7,7 +7,8 @@ import ( // Compile-time proof of interface implementation. var _ SAMLSettings = (*adminSAMLSettings)(nil) -// SAMLSettings describes all the SAML admin settings. +// SAMLSettings describes all the SAML admin settings for the Admin Setting API. +// https://www.terraform.io/cloud-docs/api-docs/admin/settings type SAMLSettings interface { // Read returns the SAML settings. Read(ctx context.Context) (*AdminSAMLSetting, error) diff --git a/admin_setting_smtp.go b/admin_setting_smtp.go index 679fc0c99..9aeffe437 100644 --- a/admin_setting_smtp.go +++ b/admin_setting_smtp.go @@ -7,7 +7,7 @@ import ( // Compile-time proof of interface implementation. var _ SMTPSettings = (*adminSMTPSettings)(nil) -// SMTPSettings describes all the SMTP admin settings. +// SMTPSettings describes all the SMTP admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings. type SMTPSettings interface { // Read returns the SMTP settings. Read(ctx context.Context) (*AdminSMTPSetting, error) @@ -77,7 +77,7 @@ type AdminSMTPSettingsUpdateOptions struct { TestEmailAddress *string `jsonapi:"attr,test-email-address,omitempty"` } -// Updat updates the SMTP settings. +// Update updates the SMTP settings. func (a *adminSMTPSettings) Update(ctx context.Context, options AdminSMTPSettingsUpdateOptions) (*AdminSMTPSetting, error) { if err := options.valid(); err != nil { return nil, err diff --git a/admin_setting_twilio.go b/admin_setting_twilio.go index 925245239..6913f2048 100644 --- a/admin_setting_twilio.go +++ b/admin_setting_twilio.go @@ -7,7 +7,8 @@ import ( // Compile-time proof of interface implementation. var _ TwilioSettings = (*adminTwilioSettings)(nil) -// TwilioSettings describes all the Twilio admin settings. +// TwilioSettings describes all the Twilio admin settings for the Admin Setting API. +// https://www.terraform.io/cloud-docs/api-docs/admin/settings. type TwilioSettings interface { // Read returns the Twilio settings. Read(ctx context.Context) (*AdminTwilioSetting, error) @@ -60,7 +61,7 @@ type AdminTwilioSettingsUpdateOptions struct { // AdminTwilioSettingsVerifyOptions represents the test number to verify Twilio. // https://www.terraform.io/docs/cloud/api/admin/settings.html#verify-twilio-settings type AdminTwilioSettingsVerifyOptions struct { - TestNumber *string `jsonapi:"attr,test-number"` + TestNumber *string `jsonapi:"attr,test-number"` // Required } // Update updates the Twilio settings. diff --git a/admin_terraform_version.go b/admin_terraform_version.go index eaccce1e2..10eb9e12e 100644 --- a/admin_terraform_version.go +++ b/admin_terraform_version.go @@ -57,10 +57,10 @@ type AdminTerraformVersion struct { type AdminTerraformVersionsListOptions struct { ListOptions - // A query string to find an exact version + // Optional: A query string to find an exact version Filter string `url:"filter[version],omitempty"` - // A search query string to find all versions that match version substring + // Optional: A search query string to find all versions that match version substring Search string `url:"search[version],omitempty"` } @@ -68,9 +68,9 @@ type AdminTerraformVersionsListOptions struct { // https://www.terraform.io/docs/cloud/api/admin/terraform-versions.html#request-body type AdminTerraformVersionCreateOptions struct { Type string `jsonapi:"primary,terraform-versions"` - Version *string `jsonapi:"attr,version"` - URL *string `jsonapi:"attr,url"` - Sha *string `jsonapi:"attr,sha"` + Version *string `jsonapi:"attr,version"` // Required + URL *string `jsonapi:"attr,url"` // Required + Sha *string `jsonapi:"attr,sha"` // Required Official *bool `jsonapi:"attr,official,omitempty"` Deprecated *bool `jsonapi:"attr,deprecated,omitempty"` DeprecatedReason *string `jsonapi:"attr,deprecated-reason,omitempty"` diff --git a/admin_user.go b/admin_user.go index 67033afcd..668ca6abe 100644 --- a/admin_user.go +++ b/admin_user.go @@ -64,7 +64,7 @@ type AdminUserList struct { Items []*AdminUser } -// A list of relations to include. See available resources +// AdminUserIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/admin/users.html#available-related-resources type AdminUserIncludeOps string @@ -77,15 +77,17 @@ const ( type AdminUserListOptions struct { ListOptions - // A search query string. Users are searchable by username and email address. + // Optional: A search query string. Users are searchable by username and email address. Query string `url:"q,omitempty"` - // Can be "true" or "false" to show only administrators or non-administrators. + // Optional: Can be "true" or "false" to show only administrators or non-administrators. Administrators string `url:"filter[admin],omitempty"` - // Can be "true" or "false" to show only suspended users or users who are not suspended. + // Optional: Can be "true" or "false" to show only suspended users or users who are not suspended. SuspendedUsers string `url:"filter[suspended],omitempty"` + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/docs/cloud/api/admin/users.html#available-related-resources Include []AdminUserIncludeOps `url:"include,omitempty"` } diff --git a/admin_workspace.go b/admin_workspace.go index 16a047d66..ae1729538 100644 --- a/admin_workspace.go +++ b/admin_workspace.go @@ -24,11 +24,12 @@ type AdminWorkspaces interface { Delete(ctx context.Context, workspaceID string) error } -// adminWorkspaces implements AdminWorkspaces. +// adminWorkspaces implements AdminWorkspaces interface. type adminWorkspaces struct { client *Client } +// AdminVCSRepo represents a VCS repository type AdminVCSRepo struct { Identifier string `jsonapi:"attr,identifier"` } @@ -45,7 +46,7 @@ type AdminWorkspace struct { CurrentRun *Run `jsonapi:"relation,current-run"` } -// A list of relations to include. See available resources +// AdminWorkspaceIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/admin/workspaces.html#available-related-resources type AdminWorkspaceIncludeOps string @@ -62,7 +63,8 @@ type AdminWorkspaceListOptions struct { // A query string (partial workspace name) used to filter the results. // https://www.terraform.io/docs/cloud/api/admin/workspaces.html#query-parameters Query string `url:"q,omitempty"` - + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/docs/cloud/api/admin/workspaces.html#available-related-resources Include []AdminWorkspaceIncludeOps `url:"include,omitempty"` } @@ -72,7 +74,7 @@ type AdminWorkspaceList struct { Items []*AdminWorkspace } -// List all the workspaces within a worksapce. +// List all the workspaces within a workspace. func (s *adminWorkspaces) List(ctx context.Context, options *AdminWorkspaceListOptions) (*AdminWorkspaceList, error) { u := "admin/workspaces" req, err := s.client.newRequest("GET", u, options) diff --git a/agent_pool.go b/agent_pool.go index c90298ac0..7e3a13099 100644 --- a/agent_pool.go +++ b/agent_pool.go @@ -63,7 +63,7 @@ type AgentPoolCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,agent-pools"` - // A name to identify the agent pool. + // Required: A name to identify the agent pool. Name *string `jsonapi:"attr,name"` } diff --git a/apply.go b/apply.go index 4f35c7482..b18680f07 100644 --- a/apply.go +++ b/apply.go @@ -23,7 +23,7 @@ type Applies interface { Logs(ctx context.Context, applyID string) (io.Reader, error) } -// applies implements Applys. +// applies implements Applies interface. type applies struct { client *Client } diff --git a/configuration_version.go b/configuration_version.go index 8d9e1d482..5ed191cf0 100644 --- a/configuration_version.go +++ b/configuration_version.go @@ -98,7 +98,7 @@ type CVStatusTimestamps struct { StartedAt time.Time `jsonapi:"attr,started-at,rfc3339"` } -// A list of relations to include. See available resources: +// ConfigurationVersionIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources type ConfigurationVersionIncludeOps string @@ -109,6 +109,8 @@ const ( // ConfigurationVersionReadOptions represents the options for reading a configuration version. type ConfigurationVersionReadOptions struct { + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources Include []ConfigurationVersionIncludeOps `url:"include,omitempty"` } @@ -116,7 +118,8 @@ type ConfigurationVersionReadOptions struct { // configuration versions. type ConfigurationVersionListOptions struct { ListOptions - + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources Include []ConfigurationVersionIncludeOps `url:"include,omitempty"` } @@ -129,11 +132,11 @@ type ConfigurationVersionCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,configuration-versions"` - // When true, runs are queued automatically when the configuration version + // Optional: When true, runs are queued automatically when the configuration version // is uploaded. AutoQueueRuns *bool `jsonapi:"attr,auto-queue-runs,omitempty"` - // When true, this configuration version can only be used for planning. + // Optional: When true, this configuration version can only be used for planning. Speculative *bool `jsonapi:"attr,speculative,omitempty"` } diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 910bc3fa7..101167525 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -130,7 +130,7 @@ func (s *example) Create(ctx context.Context, organization string, options Examp return r, nil } -// A list of relations to include with an example. See available resources: +// ExampleIncludeOps represents the available options for include query params. // https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL) type ExampleIncludeOps string @@ -142,7 +142,8 @@ const ( type ExampleListOptions struct { ListOptions - // A list of relations to include + // Optional: A list of relations to include with an example. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL) Include []ExampleIncludeOps `url:"include,omitempty"` } @@ -174,6 +175,8 @@ func (s *example) Read(ctx context.Context, exampleID string) (*Example, error) // ExampleReadOptions represents the set of options for reading an example type ExampleReadOptions struct { + // Optional: A list of relations to include with an example. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL) Include []RunTaskIncludeOps `url:"include,omitempty"` } diff --git a/errors.go b/errors.go index 369301599..53b47c890 100644 --- a/errors.go +++ b/errors.go @@ -25,29 +25,23 @@ var ( // Library errors that usually indicate a bug in the implementation of go-tfe var ( - // ErrItemsMustBeSlice is returned when an API response attribute called Items is not a slice - ErrItemsMustBeSlice = errors.New(`model field "Items" must be a slice`) + ErrItemsMustBeSlice = errors.New(`model field "Items" must be a slice`) // ErrItemsMustBeSlice is returned when an API response attribute called Items is not a slice - // ErrInvalidRequestBody is returned when a request body for DELETE/PATCH/POST is not a reference type - ErrInvalidRequestBody = errors.New("go-tfe bug: DELETE/PATCH/POST body must be nil, ptr, or ptr slice") + ErrInvalidRequestBody = errors.New("go-tfe bug: DELETE/PATCH/POST body must be nil, ptr, or ptr slice") // ErrInvalidRequestBody is returned when a request body for DELETE/PATCH/POST is not a reference type - // ErrInvalidStructFormat is returned when a mix of json and jsonapi tagged fields are used in the same struct - ErrInvalidStructFormat = errors.New("go-tfe bug: struct can't use both json and jsonapi attributes") + ErrInvalidStructFormat = errors.New("go-tfe bug: struct can't use both json and jsonapi attributes") // ErrInvalidStructFormat is returned when a mix of json and jsonapi tagged fields are used in the same struct ) // Resource Errors var ( - // ErrWorkspaceLocked is returned when trying to lock a + ErrWorkspaceLocked = errors.New("workspace already locked") // ErrWorkspaceLocked is returned when trying to lock a // locked workspace. - ErrWorkspaceLocked = errors.New("workspace already locked") - // ErrWorkspaceNotLocked is returned when trying to unlock + ErrWorkspaceNotLocked = errors.New("workspace already unlocked") // ErrWorkspaceNotLocked is returned when trying to unlock // a unlocked workspace. - ErrWorkspaceNotLocked = errors.New("workspace already unlocked") - // ErrWorkspaceLockedByRun is returned when trying to unlock a + ErrWorkspaceLockedByRun = errors.New("unable to unlock workspace locked by run") // ErrWorkspaceLockedByRun is returned when trying to unlock a // workspace locked by a run - ErrWorkspaceLockedByRun = errors.New("unable to unlock workspace locked by run") ) // Invalid values for resources/struct fields diff --git a/ip_ranges.go b/ip_ranges.go index 162a797f5..c03e3fd1f 100644 --- a/ip_ranges.go +++ b/ip_ranges.go @@ -2,10 +2,6 @@ package tfe import ( "context" - "encoding/json" - "fmt" - - "github.com/hashicorp/go-retryablehttp" ) // Compile-time proof of interface implementation. @@ -22,10 +18,12 @@ type IPRanges interface { Read(ctx context.Context, modifiedSince string) (*IPRange, error) } +// ipRanges implements IPRanges interface. type ipRanges struct { client *Client } +// IPRange represents a list of Terraform Cloud's IP ranges type IPRange struct { // List of IP ranges in CIDR notation used for connections from user site to Terraform Cloud APIs API []string `json:"api"` @@ -37,6 +35,7 @@ type IPRange struct { VCS []string `json:"vcs"` } +// Read an IPRange that was not modified since the specified date. func (i *ipRanges) Read(ctx context.Context, modifiedSince string) (*IPRange, error) { req, err := i.client.newRequest("GET", "/api/meta/ip-ranges", nil) if err != nil { @@ -55,42 +54,3 @@ func (i *ipRanges) Read(ctx context.Context, modifiedSince string) (*IPRange, er return ir, nil } - -// The IP ranges API is not returning jsonapi like every other endpoint -// which means we need to handle it differently. -func (i *ipRanges) customDo(ctx context.Context, req *retryablehttp.Request, ir *IPRange) error { - // Wait will block until the limiter can obtain a new token - // or returns an error if the given context is canceled. - if err := i.client.limiter.Wait(ctx); err != nil { - return err - } - - // Add the context to the request. - req = req.WithContext(ctx) - - // Execute the request and check the response. - resp, err := i.client.http.Do(req) - if err != nil { - // If we got an error, and the context has been canceled, - // the context's error is probably more useful. - select { - case <-ctx.Done(): - return ctx.Err() - default: - return err - } - } - defer resp.Body.Close() - - if resp.StatusCode < 200 && resp.StatusCode >= 400 { - return fmt.Errorf("error HTTP response while retrieving IP ranges: %d", resp.StatusCode) - } else if resp.StatusCode == 304 { - return nil - } - - err = json.NewDecoder(resp.Body).Decode(ir) - if err != nil { - return err - } - return nil -} diff --git a/notification_configuration.go b/notification_configuration.go index 0d1d71b70..3721c67e5 100644 --- a/notification_configuration.go +++ b/notification_configuration.go @@ -40,7 +40,6 @@ type notificationConfigurations struct { client *Client } -// List of available notification triggers. const ( NotificationTriggerCreated string = "run:created" NotificationTriggerPlanning string = "run:planning" @@ -114,29 +113,29 @@ type NotificationConfigurationCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,notification-configurations"` - // The destination type of the notification configuration + // Required: The destination type of the notification configuration DestinationType *NotificationDestinationType `jsonapi:"attr,destination-type"` - // Whether the notification configuration should be enabled or not + // Required: Whether the notification configuration should be enabled or not Enabled *bool `jsonapi:"attr,enabled"` - // The name of the notification configuration + // Required: The name of the notification configuration Name *string `jsonapi:"attr,name"` - // The token of the notification configuration + // Optional: The token of the notification configuration Token *string `jsonapi:"attr,token,omitempty"` - // The list of run events that will trigger notifications. + // Optional: The list of run events that will trigger notifications. Triggers []string `jsonapi:"attr,triggers,omitempty"` - // The url of the notification configuration + // Optional: The url of the notification configuration URL *string `jsonapi:"attr,url,omitempty"` - // The list of email addresses that will receive notification emails. + // Optional: The list of email addresses that will receive notification emails. // EmailAddresses is only available for TFE users. It is not available in TFC. EmailAddresses []string `jsonapi:"attr,email-addresses,omitempty"` - // The list of users belonging to the organization that will receive notification emails. + // Optional: The list of users belonging to the organization that will receive notification emails. EmailUsers []*User `jsonapi:"relation,users,omitempty"` } @@ -149,26 +148,26 @@ type NotificationConfigurationUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,notification-configurations"` - // Whether the notification configuration should be enabled or not + // Optional: Whether the notification configuration should be enabled or not Enabled *bool `jsonapi:"attr,enabled,omitempty"` - // The name of the notification configuration + // Optional: The name of the notification configuration Name *string `jsonapi:"attr,name,omitempty"` - // The token of the notification configuration + // Optional: The token of the notification configuration Token *string `jsonapi:"attr,token,omitempty"` - // The list of run events that will trigger notifications. + // Optional: The list of run events that will trigger notifications. Triggers []string `jsonapi:"attr,triggers,omitempty"` - // The url of the notification configuration + // Optional: The url of the notification configuration URL *string `jsonapi:"attr,url,omitempty"` - // The list of email addresses that will receive notification emails. + // Optional: The list of email addresses that will receive notification emails. // EmailAddresses is only available for TFE users. It is not available in TFC. EmailAddresses []string `jsonapi:"attr,email-addresses,omitempty"` - // The list of users belonging to the organization that will receive notification emails. + // Optional: The list of users belonging to the organization that will receive notification emails. EmailUsers []*User `jsonapi:"relation,users,omitempty"` } @@ -193,7 +192,7 @@ func (s *notificationConfigurations) List(ctx context.Context, workspaceID strin return ncl, nil } -// Creates a notification configuration with the given options. +// Create a notification configuration with the given options. func (s *notificationConfigurations) Create(ctx context.Context, workspaceID string, options NotificationConfigurationCreateOptions) (*NotificationConfiguration, error) { if !validStringID(&workspaceID) { return nil, ErrInvalidWorkspaceID @@ -274,7 +273,7 @@ func (s *notificationConfigurations) Delete(ctx context.Context, notificationCon return s.client.do(ctx, req, nil) } -// Verifies a notification configuration by delivering a verification +// Verify a notification configuration by delivering a verification // payload to the configured url. func (s *notificationConfigurations) Verify(ctx context.Context, notificationConfigurationID string) (*NotificationConfiguration, error) { if !validStringID(¬ificationConfigurationID) { diff --git a/oauth_client.go b/oauth_client.go index ab7a3c41d..ade11a209 100644 --- a/oauth_client.go +++ b/oauth_client.go @@ -99,29 +99,29 @@ type OAuthClientCreateOptions struct { // A display name for the OAuth Client. Name *string `jsonapi:"attr,name"` - // The base URL of your VCS provider's API. + // Required: The base URL of your VCS provider's API. APIURL *string `jsonapi:"attr,api-url"` - // The homepage of your VCS provider. + // Required: The homepage of your VCS provider. HTTPURL *string `jsonapi:"attr,http-url"` - // The OAuth Client key. + // Optional: The OAuth Client key. Key *string `jsonapi:"attr,key,omitempty"` - // The token string you were given by your VCS provider. + // Optional: The token string you were given by your VCS provider. OAuthToken *string `jsonapi:"attr,oauth-token-string,omitempty"` - // Private key associated with this vcs provider - only available for ado_server + // Optional: Private key associated with this vcs provider - only available for ado_server PrivateKey *string `jsonapi:"attr,private-key,omitempty"` - // Secret key associated with this vcs provider - only available for ado_server + // Optional: Secret key associated with this vcs provider - only available for ado_server Secret *string `jsonapi:"attr,secret,omitempty"` - // RSAPublicKey the text of the SSH public key associated with your BitBucket + // Optional: RSAPublicKey the text of the SSH public key associated with your BitBucket // Server Application Link. RSAPublicKey *string `jsonapi:"attr,rsa-public-key,omitempty"` - // The VCS provider being connected with. + // Required: The VCS provider being connected with. ServiceProvider *ServiceProviderType `jsonapi:"attr,service-provider"` } @@ -133,20 +133,20 @@ type OAuthClientUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,oauth-clients"` - // A display name for the OAuth Client. + // Optional: A display name for the OAuth Client. Name *string `jsonapi:"attr,name,omitempty"` - // The OAuth Client key. + // Optional: The OAuth Client key. Key *string `jsonapi:"attr,key,omitempty"` - // Secret key associated with this vcs provider - only available for ado_server + // Optional: Secret key associated with this vcs provider - only available for ado_server Secret *string `jsonapi:"attr,secret,omitempty"` - // RSAPublicKey the text of the SSH public key associated with your BitBucket + // Optional: RSAPublicKey the text of the SSH public key associated with your BitBucket // Server Application Link. RSAPublicKey *string `jsonapi:"attr,rsa-public-key,omitempty"` - // The token string you were given by your VCS provider. + // Optional: The token string you were given by your VCS provider. OAuthToken *string `jsonapi:"attr,oauth-token-string,omitempty"` } diff --git a/oauth_token.go b/oauth_token.go index 6fdb26f71..2c882498c 100644 --- a/oauth_token.go +++ b/oauth_token.go @@ -66,7 +66,7 @@ type OAuthTokenUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,oauth-tokens"` - // A private SSH key to be used for git clone operations. + // Optional: A private SSH key to be used for git clone operations. PrivateSSHKey *string `jsonapi:"attr,ssh-key,omitempty"` } diff --git a/organization.go b/organization.go index 1ee1c6c31..1a4e7da64 100644 --- a/organization.go +++ b/organization.go @@ -133,28 +133,28 @@ type OrganizationCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,organizations"` - // Name of the organization. + // Required: Name of the organization. Name *string `jsonapi:"attr,name"` - // Admin email address. + // Required: Admin email address. Email *string `jsonapi:"attr,email"` - // Session expiration (minutes). + // Optional: Session expiration (minutes). SessionRemember *int `jsonapi:"attr,session-remember,omitempty"` - // Session timeout after inactivity (minutes). + // Optional: Session timeout after inactivity (minutes). SessionTimeout *int `jsonapi:"attr,session-timeout,omitempty"` - // Authentication policy. + // Optional: Authentication policy. CollaboratorAuthPolicy *AuthPolicyType `jsonapi:"attr,collaborator-auth-policy,omitempty"` - // Enable Cost Estimation + // Optional: Enable Cost Estimation CostEstimationEnabled *bool `jsonapi:"attr,cost-estimation-enabled,omitempty"` - // The name of the "owners" team + // Optional: The name of the "owners" team OwnersTeamSAMLRoleID *string `jsonapi:"attr,owners-team-saml-role-id,omitempty"` - // SendPassingStatusesForUntriggeredSpeculativePlans toggles behavior of untriggered speculative plans to send status updates to version control systems like GitHub. + // Optional: SendPassingStatusesForUntriggeredSpeculativePlans toggles behavior of untriggered speculative plans to send status updates to version control systems like GitHub. SendPassingStatusesForUntriggeredSpeculativePlans *bool `jsonapi:"attr,send-passing-statuses-for-untriggered-speculative-plans,omitempty"` } diff --git a/organization_membership.go b/organization_membership.go index dfd09501a..02d7c5e0d 100644 --- a/organization_membership.go +++ b/organization_membership.go @@ -39,10 +39,9 @@ type organizationMemberships struct { // OrganizationMembershipStatus represents an organization membership status. type OrganizationMembershipStatus string -// List all available organization membership statuses. const ( - OrganizationMembershipActive = "active" - OrganizationMembershipInvited = "invited" + OrganizationMembershipActive OrganizationMembershipStatus = "active" + OrganizationMembershipInvited OrganizationMembershipStatus = "invited" ) // OrganizationMembershipList represents a list of organization memberships. @@ -63,6 +62,7 @@ type OrganizationMembership struct { Teams []*Team `jsonapi:"relation,teams"` } +// OrganizationMembershipIncludeOps represents the available options for include query params. // https://www.terraform.io/cloud-docs/api-docs/organization-memberships#available-related-resources type OrganizationMembershipIncludeOps string @@ -74,7 +74,8 @@ const ( // OrganizationMembershipListOptions represents the options for listing organization memberships. type OrganizationMembershipListOptions struct { ListOptions - + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/cloud-docs/api-docs/organization-memberships#available-related-resources Include []OrganizationMembershipIncludeOps `url:"include,omitempty"` } @@ -86,12 +87,14 @@ type OrganizationMembershipCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,organization-memberships"` - // User's email address. + // Required: User's email address. Email *string `jsonapi:"attr,email"` } // OrganizationMembershipReadOptions represents the options for reading organization memberships. type OrganizationMembershipReadOptions struct { + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/cloud-docs/api-docs/organization-memberships#available-related-resources Include []OrganizationMembershipIncludeOps `url:"include,omitempty"` } diff --git a/organization_tags.go b/organization_tags.go index 631d0c0dc..bbf756f74 100644 --- a/organization_tags.go +++ b/organization_tags.go @@ -9,6 +9,10 @@ import ( var _ OrganizationTags = (*organizationTags)(nil) +// OrganizationMemberships describes all the list of tags used with all resources across the organization. +// +// TFE API docs: +// https://www.terraform.io/cloud-docs/api-docs/organization-tags type OrganizationTags interface { // List all tags within an organization List(ctx context.Context, organization string, options *OrganizationTagsListOptions) (*OrganizationTagsList, error) @@ -20,6 +24,7 @@ type OrganizationTags interface { AddWorkspaces(ctx context.Context, tag string, options AddWorkspacesToTagOptions) error } +// organizationTags implements OrganizationTags. type organizationTags struct { client *Client } @@ -32,10 +37,11 @@ type OrganizationTagsList struct { // OrganizationTag represents a Terraform Enterprise Organization tag type OrganizationTag struct { - ID string `jsonapi:"primary,tags"` + ID string `jsonapi:"primary,tags"` + // Optional: Name string `jsonapi:"attr,name,omitempty"` - // Number of workspaces that have this tag + // Optional: Number of workspaces that have this tag InstanceCount int `jsonapi:"attr,instance-count,omitempty"` // The org this tag belongs to @@ -45,18 +51,18 @@ type OrganizationTag struct { // OrganizationTagsListOptions represents the options for listing organization tags type OrganizationTagsListOptions struct { ListOptions - + // Optional: Filter string `url:"filter[exclude][taggable][id],omitempty"` } // OrganizationTagsDeleteOptions represents the request body for deleting a tag in an organization type OrganizationTagsDeleteOptions struct { - IDs []string + IDs []string // Required } // AddWorkspacesToTagOptions represents the request body to add a workspace to a tag type AddWorkspacesToTagOptions struct { - WorkspaceIDs []string + WorkspaceIDs []string // Required } // this represents a single tag ID diff --git a/plan.go b/plan.go index 57dcb6de1..67674be87 100644 --- a/plan.go +++ b/plan.go @@ -15,7 +15,7 @@ var _ Plans = (*plans)(nil) // Plans describes all the plan related methods that the Terraform Enterprise // API supports. // -// TFE API docs: https://www.terraform.io/docs/cloud/api/plan.html +// TFE API docs: https://www.terraform.io/cloud-docs/api-docs/plans type Plans interface { // Read a plan by its ID. Read(ctx context.Context, planID string) (*Plan, error) diff --git a/plan_export.go b/plan_export.go index 48c7ee644..35dc907b1 100644 --- a/plan_export.go +++ b/plan_export.go @@ -80,13 +80,14 @@ type PlanExportCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,plan-exports"` - // The plan to export. + // Required: The plan to export. Plan *Plan `jsonapi:"relation,plan"` - // The name of the policy set. + // Required: The name of the policy set. DataType *PlanExportDataType `jsonapi:"attr,data-type"` } +// Create a plan export func (s *planExports) Create(ctx context.Context, options PlanExportCreateOptions) (*PlanExport, error) { if err := options.valid(); err != nil { return nil, err diff --git a/policy.go b/policy.go index 957261dfe..49a293a5a 100644 --- a/policy.go +++ b/policy.go @@ -88,7 +88,7 @@ type EnforcementOptions struct { type PolicyListOptions struct { ListOptions - // A search string (partial policy name) used to filter the results. + // Optional: A search string (partial policy name) used to filter the results. Search string `url:"search[name],omitempty"` } @@ -100,13 +100,13 @@ type PolicyCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,policies"` - // The name of the policy. + // Required: The name of the policy. Name *string `jsonapi:"attr,name"` - // A description of the policy's purpose. + // Optional: A description of the policy's purpose. Description *string `jsonapi:"attr,description,omitempty"` - // The enforcements of the policy. + // Required: The enforcements of the policy. Enforce []*EnforcementOptions `jsonapi:"attr,enforce"` } @@ -118,10 +118,10 @@ type PolicyUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,policies"` - // A description of the policy's purpose. + // Optional: A description of the policy's purpose. Description *string `jsonapi:"attr,description,omitempty"` - // The enforcements of the policy. + // Optional: The enforcements of the policy. Enforce []*EnforcementOptions `jsonapi:"attr,enforce,omitempty"` } diff --git a/policy_set.go b/policy_set.go index 6a39e1fc5..2535f5a11 100644 --- a/policy_set.go +++ b/policy_set.go @@ -13,7 +13,7 @@ var _ PolicySets = (*policySets)(nil) // PolicySets describes all the policy set related methods that the Terraform // Enterprise API supports. // -// TFE API docs: https://www.terraform.io/docs/cloud/api/policies.html +// TFE API docs: https://www.terraform.io/docs/cloud/api/policy-sets.html type PolicySets interface { // List all the policy sets for a given organization. List(ctx context.Context, organization string, options *PolicySetListOptions) (*PolicySetList, error) @@ -87,6 +87,7 @@ type PolicySet struct { CurrentVersion *PolicySetVersion `jsonapi:"relation,current-version"` } +// PolicySetIncludeOps represents the available options for include query params. type PolicySetIncludeOps string const ( @@ -100,7 +101,7 @@ const ( type PolicySetListOptions struct { ListOptions - // A search string (partial policy set name) used to filter the results. + // Optional: A search string (partial policy set name) used to filter the results. Search string `url:"search[name],omitempty"` } @@ -108,6 +109,8 @@ type PolicySetListOptions struct { // For a full list of relations, please see: // https://www.terraform.io/docs/cloud/api/policy-sets.html#relationships type PolicySetReadOptions struct { + // Optional: A list of relations to include. See available resources + // https://www.terraform.io/cloud-docs/api-docs/policy-sets#relationships Include []PolicySetIncludeOps `url:"include,omitempty"` } @@ -119,31 +122,31 @@ type PolicySetCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,policy-sets"` - // The name of the policy set. + // Required: The name of the policy set. Name *string `jsonapi:"attr,name"` - // The description of the policy set. + // Optional: The description of the policy set. Description *string `jsonapi:"attr,description,omitempty"` - // Whether or not the policy set is global. + // Optional: Whether or not the policy set is global. Global *bool `jsonapi:"attr,global,omitempty"` - // The sub-path within the attached VCS repository to ingress. All + // Optional: The sub-path within the attached VCS repository to ingress. All // files and directories outside of this sub-path will be ignored. // This option may only be specified when a VCS repo is present. PoliciesPath *string `jsonapi:"attr,policies-path,omitempty"` - // The initial members of the policy set. + // Optional: The initial members of the policy set. Policies []*Policy `jsonapi:"relation,policies,omitempty"` - // VCS repository information. When present, the policies and + // Optional: VCS repository information. When present, the policies and // configuration will be sourced from the specified VCS repository // instead of being defined within the policy set itself. Note that // this option is mutually exclusive with the Policies option and // both cannot be used at the same time. VCSRepo *VCSRepoOptions `jsonapi:"attr,vcs-repo,omitempty"` - // The initial list of workspaces for which the policy set should be enforced. + // Optional: The initial list of workspaces for which the policy set should be enforced. Workspaces []*Workspace `jsonapi:"relation,workspaces,omitempty"` } @@ -155,21 +158,21 @@ type PolicySetUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,policy-sets"` - // The name of the policy set. + // Optional: The name of the policy set. Name *string `jsonapi:"attr,name,omitempty"` - // The description of the policy set. + // Optional: The description of the policy set. Description *string `jsonapi:"attr,description,omitempty"` - // Whether or not the policy set is global. + // Optional: Whether or not the policy set is global. Global *bool `jsonapi:"attr,global,omitempty"` - // The sub-path within the attached VCS repository to ingress. All + // Optional: The sub-path within the attached VCS repository to ingress. All // files and directories outside of this sub-path will be ignored. // This option may only be specified when a VCS repo is present. PoliciesPath *string `jsonapi:"attr,policies-path,omitempty"` - // VCS repository information. When present, the policies and + // Optional: VCS repository information. When present, the policies and // configuration will be sourced from the specified VCS repository // instead of being defined within the policy set itself. Note that // specifying this option may only be used on policy sets with no @@ -301,7 +304,7 @@ func (s *policySets) Update(ctx context.Context, policySetID string, options Pol return ps, err } -// Add policies to a policy set +// AddPolicies adds policies to a policy set func (s *policySets) AddPolicies(ctx context.Context, policySetID string, options PolicySetAddPoliciesOptions) error { if !validStringID(&policySetID) { return ErrInvalidPolicySetID @@ -319,7 +322,7 @@ func (s *policySets) AddPolicies(ctx context.Context, policySetID string, option return s.client.do(ctx, req, nil) } -// Remove policies from a policy set +// RemovePolicies remove policies from a policy set func (s *policySets) RemovePolicies(ctx context.Context, policySetID string, options PolicySetRemovePoliciesOptions) error { if !validStringID(&policySetID) { return ErrInvalidPolicySetID @@ -337,7 +340,7 @@ func (s *policySets) RemovePolicies(ctx context.Context, policySetID string, opt return s.client.do(ctx, req, nil) } -// Add workspaces to a policy set. +// Addworkspaces adds workspaces to a policy set. func (s *policySets) AddWorkspaces(ctx context.Context, policySetID string, options PolicySetAddWorkspacesOptions) error { if !validStringID(&policySetID) { return ErrInvalidPolicySetID @@ -355,7 +358,7 @@ func (s *policySets) AddWorkspaces(ctx context.Context, policySetID string, opti return s.client.do(ctx, req, nil) } -// Remove workspaces from a policy set. +// RemoveWorkspaces removes workspaces from a policy set. func (s *policySets) RemoveWorkspaces(ctx context.Context, policySetID string, options PolicySetRemoveWorkspacesOptions) error { if !validStringID(&policySetID) { return ErrInvalidPolicySetID diff --git a/policy_set_parameter.go b/policy_set_parameter.go index d526bdb72..5d5201756 100644 --- a/policy_set_parameter.go +++ b/policy_set_parameter.go @@ -66,16 +66,16 @@ type PolicySetParameterCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,vars"` - // The name of the parameter. + // Required: The name of the parameter. Key *string `jsonapi:"attr,key"` - // The value of the parameter. + // Optional: The value of the parameter. Value *string `jsonapi:"attr,value,omitempty"` - // The Category of the parameter, should always be "policy-set" + // Required: The Category of the parameter, should always be "policy-set" Category *CategoryType `jsonapi:"attr,category"` - // Whether the value is sensitive. + // Optional: Whether the value is sensitive. Sensitive *bool `jsonapi:"attr,sensitive,omitempty"` } @@ -87,13 +87,13 @@ type PolicySetParameterUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,vars"` - // The name of the parameter. + // Optional: The name of the parameter. Key *string `jsonapi:"attr,key,omitempty"` - // The value of the parameter. + // Optional: The value of the parameter. Value *string `jsonapi:"attr,value,omitempty"` - // Whether the value is sensitive. + // Optional: Whether the value is sensitive. Sensitive *bool `jsonapi:"attr,sensitive,omitempty"` } diff --git a/policy_set_version.go b/policy_set_version.go index 33007a35a..6d31ae876 100644 --- a/policy_set_version.go +++ b/policy_set_version.go @@ -64,6 +64,7 @@ type PolicySetVersionStatusTimestamps struct { ErroredAt time.Time `jsonapi:"attr,errored-at,rfc3339"` } +// PolicySetVersion represents a Terraform Enterprise Policy Set Version type PolicySetVersion struct { ID string `jsonapi:"primary,policy-set-versions"` Source PolicySetVersionSource `jsonapi:"attr,source"` diff --git a/registry_module.go b/registry_module.go index 648e47359..67c4bb66e 100644 --- a/registry_module.go +++ b/registry_module.go @@ -122,8 +122,9 @@ type RegistryModuleCreateOptions struct { // It is not a user-defined value and does not need to be set. // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,registry-modules"` - - Name *string `jsonapi:"attr,name"` + // Required: + Name *string `jsonapi:"attr,name"` + // Required: Provider *string `jsonapi:"attr,provider"` } @@ -146,14 +147,14 @@ type RegistryModuleCreateWithVCSConnectionOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,registry-modules"` - // VCS repository information + // Required: VCS repository information VCSRepo *RegistryModuleVCSRepoOptions `jsonapi:"attr,vcs-repo"` } type RegistryModuleVCSRepoOptions struct { - Identifier *string `json:"identifier"` - OAuthTokenID *string `json:"oauth-token-id"` - DisplayIdentifier *string `json:"display-identifier"` + Identifier *string `json:"identifier"` // Required + OAuthTokenID *string `json:"oauth-token-id"` // Required + DisplayIdentifier *string `json:"display-identifier"` // Required } // Upload uploads Terraform configuration files for the provided registry module version. It @@ -205,7 +206,7 @@ func (r *registryModules) Create(ctx context.Context, organization string, optio return rm, nil } -// Create a new registry module version +// CreateVersion creates a new registry module version func (r *registryModules) CreateVersion(ctx context.Context, organization, name, provider string, options RegistryModuleCreateVersionOptions) (*RegistryModuleVersion, error) { if !validStringID(&organization) { return nil, ErrInvalidOrg diff --git a/run.go b/run.go index e07b42f03..df06b4bef 100644 --- a/run.go +++ b/run.go @@ -158,7 +158,7 @@ type RunStatusTimestamps struct { PolicySoftFailedAt time.Time `jsonapi:"attr,policy-soft-failed-at,rfc3339"` } -// A list of relations to include. See available resources: +// RunIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/run.html#available-related-resources type RunIncludeOps string @@ -176,12 +176,15 @@ const ( // RunListOptions represents the options for listing runs. type RunListOptions struct { ListOptions - + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/docs/cloud/api/run.html#available-related-resources Include []RunIncludeOps `url:"include,omitempty"` } // RunReadOptions represents the options for reading a run. type RunReadOptions struct { + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/docs/cloud/api/run.html#available-related-resources Include []RunIncludeOps `url:"include,omitempty"` } diff --git a/run_task.go b/run_task.go index fb537fac1..fb3bb8a28 100644 --- a/run_task.go +++ b/run_task.go @@ -12,6 +12,7 @@ var _ RunTasks = (*runTasks)(nil) // RunTasks represents all the run task related methods in the context of an organization // that the Terraform Cloud/Enterprise API supports. // **Note: This API is still in BETA and subject to change.** +// https://www.terraform.io/cloud-docs/api-docs/run-tasks#run-tasks-api type RunTasks interface { // Create a run task for an organization Create(ctx context.Context, organization string, options RunTaskCreateOptions) (*RunTask, error) @@ -58,7 +59,7 @@ type RunTaskList struct { Items []*RunTask } -// A list of relations to include with a run task. See available resources: +// RunTaskIncludeOps represents the available options for include query params. // https://www.terraform.io/cloud-docs/api-docs/run-tasks#list-run-tasks type RunTaskIncludeOps string @@ -70,13 +71,15 @@ const ( // RunTaskListOptions represents the set of options for listing run tasks type RunTaskListOptions struct { ListOptions - - // A list of relations to include - Include []RunTaskIncludeOps `url:"include"` + // Optional: A list of relations to include with a run task. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/run-tasks#list-run-tasks + Include []RunTaskIncludeOps `url:"include,omitempty"` } // RunTaskReadOptions represents the set of options for reading a run task type RunTaskReadOptions struct { + // Optional: A list of relations to include with a run task. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/run-tasks#list-run-tasks Include []RunTaskIncludeOps `url:"include"` } @@ -234,7 +237,7 @@ func (s *runTasks) Delete(ctx context.Context, runTaskID string) error { return s.client.do(ctx, req, nil) } -// Convenient method to attach a run task to a workspace. See: WorkspaceRunTasks.Create() +// AttachToWorkspace is a convenient method to attach a run task to a workspace. See: WorkspaceRunTasks.Create() func (s *runTasks) AttachToWorkspace(ctx context.Context, workspaceID, runTaskID string, enforcement TaskEnforcementLevel) (*WorkspaceRunTask, error) { return s.client.WorkspaceRunTasks.Create(ctx, workspaceID, WorkspaceRunTaskCreateOptions{ EnforcementLevel: enforcement, diff --git a/run_trigger.go b/run_trigger.go index dc7939e50..04c08237e 100644 --- a/run_trigger.go +++ b/run_trigger.go @@ -111,7 +111,7 @@ func (s *runTriggers) List(ctx context.Context, workspaceID string, options *Run return rtl, nil } -// Creates a run trigger with the given options. +// Create a run trigger with the given options. func (s *runTriggers) Create(ctx context.Context, workspaceID string, options RunTriggerCreateOptions) (*RunTrigger, error) { if !validStringID(&workspaceID) { return nil, ErrInvalidWorkspaceID diff --git a/ssh_key.go b/ssh_key.go index 1ff5d026b..d2faea2d4 100644 --- a/ssh_key.go +++ b/ssh_key.go @@ -73,7 +73,7 @@ type SSHKeyUpdateOptions struct { // For internal use only! ID string `jsonapi:"primary,ssh-keys"` - // A new name to identify the SSH key. + // Optional: A new name to identify the SSH key. Name *string `jsonapi:"attr,name,omitempty"` } diff --git a/state_version.go b/state_version.go index ec16b9a27..83fef04a1 100644 --- a/state_version.go +++ b/state_version.go @@ -80,6 +80,7 @@ type StateVersionListOptions struct { Workspace string `url:"filter[workspace][name]"` } +// StateVersionIncludeOps represents the available options for include query params. // https://www.terraform.io/cloud-docs/api-docs/state-versions#available-related-resources type StateVersionIncludeOps string @@ -93,6 +94,8 @@ const ( // StateVersionReadOptions represents the options for reading state version. type StateVersionReadOptions struct { + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/state-versions#available-related-resources Include []StateVersionIncludeOps `url:"include,omitempty"` } @@ -104,6 +107,8 @@ type StateVersionOutputsListOptions struct { // StateVersionCurrentOptions represents the options for reading the current state version. type StateVersionCurrentOptions struct { + // Optional: A list of relations to include. See available resources: + // https://www.terraform.io/cloud-docs/api-docs/state-versions#available-related-resources Include []StateVersionIncludeOps `url:"include,omitempty"` } @@ -115,23 +120,23 @@ type StateVersionCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,state-versions"` - // The lineage of the state. + // Optional: The lineage of the state. Lineage *string `jsonapi:"attr,lineage,omitempty"` - // The MD5 hash of the state version. + // Required: The MD5 hash of the state version. MD5 *string `jsonapi:"attr,md5"` - // The serial of the state. + // Required: The serial of the state. Serial *int64 `jsonapi:"attr,serial"` - // The base64 encoded state. + // Required: The base64 encoded state. State *string `jsonapi:"attr,state"` - // Force can be set to skip certain validations. Wrong use + // Optional: Force can be set to skip certain validations. Wrong use // of this flag can cause data loss, so USE WITH CAUTION! Force *bool `jsonapi:"attr,force,omitempty"` - // Specifies the run to associate the state with. + // Optional: Specifies the run to associate the state with. Run *Run `jsonapi:"relation,run,omitempty"` } diff --git a/state_version_output.go b/state_version_output.go index 0e91be2fc..21db1fa3f 100644 --- a/state_version_output.go +++ b/state_version_output.go @@ -18,10 +18,12 @@ type StateVersionOutputs interface { Read(ctx context.Context, outputID string) (*StateVersionOutput, error) } +// stateVersionOutputs implements StateVersionOutputs. type stateVersionOutputs struct { client *Client } +// StateVersionOutput represents a State Version Outputs type StateVersionOutput struct { ID string `jsonapi:"primary,state-version-outputs"` Name string `jsonapi:"attr,name"` @@ -30,6 +32,7 @@ type StateVersionOutput struct { Value interface{} `jsonapi:"attr,value"` } +// Read a State Version Output func (s *stateVersionOutputs) Read(ctx context.Context, outputID string) (*StateVersionOutput, error) { if !validStringID(&outputID) { return nil, ErrInvalidRunID diff --git a/task_result.go b/task_result.go index 3a492e436..4abc36706 100644 --- a/task_result.go +++ b/task_result.go @@ -24,16 +24,18 @@ type taskResults struct { // TaskResultStatus is an enum that represents all possible statuses for a task result type TaskResultStatus string -// TaskEnforcementLevel is an enum that describes the enforcement levels for a run task -type TaskEnforcementLevel string - const ( TaskPassed TaskResultStatus = "passed" TaskFailed TaskResultStatus = "failed" - TaskRunning TaskResultStatus = "running" TaskPending TaskResultStatus = "pending" + TaskRunning TaskResultStatus = "running" TaskUnreachable TaskResultStatus = "unreachable" +) +// TaskEnforcementLevel is an enum that describes the enforcement levels for a run task +type TaskEnforcementLevel string + +const ( Advisory TaskEnforcementLevel = "advisory" Mandatory TaskEnforcementLevel = "mandatory" ) diff --git a/task_stages.go b/task_stages.go index 470a84070..4000241a1 100644 --- a/task_stages.go +++ b/task_stages.go @@ -59,7 +59,7 @@ type TaskStageStatusTimestamps struct { PassedAt time.Time `jsonapi:"attr,passed-at,rfc3339"` } -// A list of relations to include. +// TaskStageIncludeOps represents the available options for include query params. type TaskStageIncludeOps string const ( @@ -68,6 +68,7 @@ const ( // TaskStageReadOptions represents the set of options when reading a task stage type TaskStageReadOptions struct { + // Optional: A list of relations to include. Include []TaskStageIncludeOps `url:"include,omitempty"` } diff --git a/team.go b/team.go index 9c9ecacac..ae2139505 100644 --- a/team.go +++ b/team.go @@ -71,9 +71,10 @@ type TeamPermissions struct { CanUpdateMembership bool `jsonapi:"attr,can-update-membership"` } +// TeamIncludeOps represents the available options for include query params. +// https://www.terraform.io/docs/cloud/api/teams.html#available-related-resources type TeamIncludeOps string -// https://www.terraform.io/docs/cloud/api/teams.html#available-related-resources const ( TeamUsers TeamIncludeOps = "users" TeamOrganizationMemberships TeamIncludeOps = "organization-memberships" @@ -82,7 +83,8 @@ const ( // TeamListOptions represents the options for listing teams. type TeamListOptions struct { ListOptions - + // Optional: A list of relations to include. + // https://www.terraform.io/docs/cloud/api/teams.html#available-related-resources Include []TeamIncludeOps `url:"include,omitempty"` } @@ -112,13 +114,13 @@ type TeamUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,teams"` - // New name for the team + // Optional: New name for the team Name *string `jsonapi:"attr,name,omitempty"` - // The team's organization access + // Optional: The team's organization access OrganizationAccess *OrganizationAccessOptions `jsonapi:"attr,organization-access,omitempty"` - // The team's visibility ("secret", "organization") + // Optional: The team's visibility ("secret", "organization") Visibility *string `jsonapi:"attr,visibility,omitempty"` } diff --git a/team_access.go b/team_access.go index 0601b10b8..2a54f458e 100644 --- a/team_access.go +++ b/team_access.go @@ -39,42 +39,46 @@ type teamAccesses struct { // AccessType represents a team access type. type AccessType string -// RunsPermissionType represents the permissiontype to a workspace's runs. -type RunsPermissionType string - -// VariablesPermissionType represents the permissiontype to a workspace's variables. -type VariablesPermissionType string - -// StateVersionsPermissionType represents the permissiontype to a workspace's state versions. -type StateVersionsPermissionType string - -// SentinelMocksPermissionType represents the permissiontype to a workspace's Sentinel mocks. -type SentinelMocksPermissionType string - -// WorkspaceLockingPermissionType represents the permissiontype to lock or unlock a workspace. -type WorkspaceLockingPermissionType bool - -// List all available team access types and permissions. const ( AccessAdmin AccessType = "admin" AccessPlan AccessType = "plan" AccessRead AccessType = "read" AccessWrite AccessType = "write" AccessCustom AccessType = "custom" +) + +// RunsPermissionType represents the permissiontype to a workspace's runs. +type RunsPermissionType string +const ( RunsPermissionRead RunsPermissionType = "read" RunsPermissionPlan RunsPermissionType = "plan" RunsPermissionApply RunsPermissionType = "apply" +) + +// VariablesPermissionType represents the permissiontype to a workspace's variables. +type VariablesPermissionType string +const ( VariablesPermissionNone VariablesPermissionType = "none" VariablesPermissionRead VariablesPermissionType = "read" VariablesPermissionWrite VariablesPermissionType = "write" +) + +// StateVersionsPermissionType represents the permissiontype to a workspace's state versions. +type StateVersionsPermissionType string +const ( StateVersionsPermissionNone StateVersionsPermissionType = "none" StateVersionsPermissionReadOutputs StateVersionsPermissionType = "read-outputs" StateVersionsPermissionRead StateVersionsPermissionType = "read" StateVersionsPermissionWrite StateVersionsPermissionType = "write" +) +// SentinelMocksPermissionType represents the permissiontype to a workspace's Sentinel mocks. +type SentinelMocksPermissionType string + +const ( SentinelMocksPermissionNone SentinelMocksPermissionType = "none" SentinelMocksPermissionRead SentinelMocksPermissionType = "read" ) @@ -249,7 +253,6 @@ func (s *teamAccesses) Remove(ctx context.Context, teamAccessID string) error { return s.client.do(ctx, req, nil) } -// check that workspaceID field has a valid value func (o *TeamAccessListOptions) valid() error { if o == nil { return ErrRequiredTeamAccessListOps diff --git a/tfe.go b/tfe.go index 86b64b5c9..118a8d52b 100644 --- a/tfe.go +++ b/tfe.go @@ -28,24 +28,24 @@ import ( ) const ( - _userAgent = "go-tfe" - _headerRateLimit = "X-RateLimit-Limit" - _headerRateReset = "X-RateLimit-Reset" - _headerAPIVersion = "TFP-API-Version" - - // DefaultAddress of Terraform Enterprise. - DefaultAddress = "https://app.terraform.io" - // DefaultBasePath on which the API is served. + _userAgent = "go-tfe" + _headerRateLimit = "X-RateLimit-Limit" + _headerRateReset = "X-RateLimit-Reset" + _headerAPIVersion = "TFP-API-Version" + _includeQueryParam = "include" + + DefaultAddress = "https://app.terraform.io" DefaultBasePath = "/api/v2/" // PingEndpoint is a no-op API endpoint used to configure the rate limiter - PingEndpoint = "ping" - IncludeQueryParam = "include" + PingEndpoint = "ping" ) // RetryLogHook allows a function to run before each retry. + type RetryLogHook func(attemptNum int, resp *http.Response) // Config provides configuration details to the API client. + type Config struct { // The address of the Terraform Enterprise API. Address string @@ -67,6 +67,7 @@ type Config struct { } // DefaultConfig returns a default config structure. + func DefaultConfig() *Config { config := &Config{ Address: os.Getenv("TFE_ADDRESS"), @@ -88,7 +89,7 @@ func DefaultConfig() *Config { } // Client is the Terraform Enterprise API client. It provides the basic -// connectivity and configuration for accessing the TFE API. +// connectivity and configuration for accessing the TFE API type Client struct { baseURL *url.URL token string @@ -143,7 +144,7 @@ type Client struct { // Admin is the the Terraform Enterprise Admin API. It provides access to site // wide admin settings. These are only available for Terraform Enterprise and -// do not function against Terraform Cloud. +// do not function against Terraform Cloud type Admin struct { Organizations AdminOrganizations Workspaces AdminWorkspaces @@ -310,18 +311,21 @@ func (c *Client) RemoteAPIVersion() string { // // This is intended for use in tests, when you may want to configure your TFE client to // return something different than the actual API version in order to test error handling. + func (c *Client) SetFakeRemoteAPIVersion(fakeAPIVersion string) { c.remoteAPIVersion = fakeAPIVersion } // RetryServerErrors configures the retry HTTP check to also retry // unexpected errors or requests that failed with a server error. + func (c *Client) RetryServerErrors(retry bool) { c.retryServerErrors = retry } // retryHTTPCheck provides a callback for Client.CheckRetry which // will retry both rate limit (429) and server (>= 500) errors. + func (c *Client) retryHTTPCheck(ctx context.Context, resp *http.Response, err error) (bool, error) { if ctx.Err() != nil { return false, ctx.Err() @@ -337,6 +341,7 @@ func (c *Client) retryHTTPCheck(ctx context.Context, resp *http.Response, err er // retryHTTPBackoff provides a generic callback for Client.Backoff which // will pass through all calls based on the status code of the response. + func (c *Client) retryHTTPBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration { if c.retryLogHook != nil { c.retryLogHook(attemptNum, resp) @@ -361,6 +366,7 @@ func (c *Client) retryHTTPBackoff(min, max time.Duration, attemptNum int, resp * // min and max are mainly used for bounding the jitter that will be added to // the reset time retrieved from the headers. But if the final wait time is // less then min, min will be used instead. + func rateLimitBackoff(min, max time.Duration, resp *http.Response) time.Duration { // rnd is used to generate pseudo-random numbers. rnd := rand.New(rand.NewSource(time.Now().UnixNano())) @@ -429,6 +435,7 @@ func (c *Client) getRawAPIMetadata() (rawAPIMetadata, error) { } // configureLimiter configures the rate limiter. + func (c *Client) configureLimiter(rawLimit string) { // Set default values for when rate limiting is disabled. limit := rate.Inf @@ -519,6 +526,7 @@ func (c *Client) newRequest(method, path string, v interface{}) (*retryablehttp. // Encode encodes the values into ``URL encoded'' form // ("bar=baz&foo=quux") sorted by key. + func encodeQueryParams(v url.Values) string { if v == nil { return "" @@ -531,7 +539,7 @@ func encodeQueryParams(v url.Values) string { sort.Strings(keys) for _, k := range keys { vs := v[k] - if len(vs) > 1 && k == IncludeQueryParam { + if len(vs) > 1 && k == _includeQueryParam { val := strings.Join(vs, ",") vs = vs[:0] vs = append(vs, val) @@ -553,6 +561,7 @@ func encodeQueryParams(v url.Values) string { // Helper method that serializes the given ptr or ptr slice into a JSON // request. It automatically uses jsonapi or json serialization, depending // on the body type's tags. + func serializeRequestBody(v interface{}) (interface{}, error) { // The body can be a slice of pointers or a pointer. In either // case we want to choose the serialization type based on the @@ -616,6 +625,7 @@ func serializeRequestBody(v interface{}) (interface{}, error) { // // The provided ctx must be non-nil. If it is canceled or times out, ctx.Err() // will be returned. + func (c *Client) do(ctx context.Context, req *retryablehttp.Request, v interface{}) error { // Wait will block until the limiter can obtain a new token // or returns an error if the given context is canceled. @@ -659,6 +669,46 @@ func (c *Client) do(ctx context.Context, req *retryablehttp.Request, v interface return unmarshalResponse(resp.Body, v) } +// customDo is similar to func (c *Client) do(ctx context.Context, req *retryablehttp.Request, v interface{}) error. Except that The IP ranges API is not returning jsonapi like every other endpoint +// which means we need to handle it differently. + +func (i *ipRanges) customDo(ctx context.Context, req *retryablehttp.Request, ir *IPRange) error { + // Wait will block until the limiter can obtain a new token + // or returns an error if the given context is canceled. + if err := i.client.limiter.Wait(ctx); err != nil { + return err + } + + // Add the context to the request. + req = req.WithContext(ctx) + + // Execute the request and check the response. + resp, err := i.client.http.Do(req) + if err != nil { + // If we got an error, and the context has been canceled, + // the context's error is probably more useful. + select { + case <-ctx.Done(): + return ctx.Err() + default: + return err + } + } + defer resp.Body.Close() + + if resp.StatusCode < 200 && resp.StatusCode >= 400 { + return fmt.Errorf("error HTTP response while retrieving IP ranges: %d", resp.StatusCode) + } else if resp.StatusCode == 304 { + return nil + } + + err = json.NewDecoder(resp.Body).Decode(ir) + if err != nil { + return err + } + return nil +} + func unmarshalResponse(responseBody io.Reader, model interface{}) error { // Get the value of model so we can test if it's a struct. dst := reflect.Indirect(reflect.ValueOf(model)) @@ -753,6 +803,7 @@ func parsePagination(body io.Reader) (*Pagination, error) { } // checkResponseCode can be used to check the status code of an HTTP request. + func checkResponseCode(r *http.Response) error { if r.StatusCode >= 200 && r.StatusCode <= 299 { return nil diff --git a/user.go b/user.go index 5e08d048d..0795f5032 100644 --- a/user.go +++ b/user.go @@ -53,10 +53,10 @@ type UserUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,users"` - // New username. + // Optional: New username. Username *string `jsonapi:"attr,username,omitempty"` - // New email address (must be consumed afterwards to take effect). + // Optional: New email address (must be consumed afterwards to take effect). Email *string `jsonapi:"attr,email,omitempty"` } @@ -76,7 +76,7 @@ func (s *users) ReadCurrent(ctx context.Context) (*User, error) { return u, nil } -// Update attributes of the currently authenticated user. +// UpdateCurrent updates attributes of the currently authenticated user. func (s *users) UpdateCurrent(ctx context.Context, options UserUpdateOptions) (*User, error) { req, err := s.client.newRequest("PATCH", "account/update", &options) if err != nil { diff --git a/user_token.go b/user_token.go index 874e7bb46..56de5b859 100644 --- a/user_token.go +++ b/user_token.go @@ -51,7 +51,7 @@ type UserToken struct { // UserTokenCreateOptions the options for creating a user token. type UserTokenCreateOptions struct { - // Description of the token + // Optional: Description of the token Description string `jsonapi:"attr,description,omitempty"` } diff --git a/validations.go b/validations.go index a260fc1b3..1f2483734 100644 --- a/validations.go +++ b/validations.go @@ -5,15 +5,18 @@ import ( ) // A regular expression used to validate common string ID patterns. + var reStringID = regexp.MustCompile(`^[a-zA-Z0-9\-._]+$`) // validString checks if the given input is present and non-empty. + func validString(v *string) bool { return v != nil && *v != "" } // validStringID checks if the given string pointer is non-nil and // contains a typical string identifier. + func validStringID(v *string) bool { return v != nil && reStringID.MatchString(*v) } diff --git a/variable.go b/variable.go index dd736fad7..d72bacaed 100644 --- a/variable.go +++ b/variable.go @@ -78,22 +78,22 @@ type VariableCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,vars"` - // The name of the variable. + // Required: The name of the variable. Key *string `jsonapi:"attr,key"` - // The value of the variable. + // Optional: The value of the variable. Value *string `jsonapi:"attr,value,omitempty"` - // The description of the variable. + // Optional: The description of the variable. Description *string `jsonapi:"attr,description,omitempty"` - // Whether this is a Terraform or environment variable. + // Required: Whether this is a Terraform or environment variable. Category *CategoryType `jsonapi:"attr,category"` - // Whether to evaluate the value of the variable as a string of HCL code. + // Optional: Whether to evaluate the value of the variable as a string of HCL code. HCL *bool `jsonapi:"attr,hcl,omitempty"` - // Whether the value is sensitive. + // Optional: Whether the value is sensitive. Sensitive *bool `jsonapi:"attr,sensitive,omitempty"` } diff --git a/workspace.go b/workspace.go index e0b09ae79..32cf5fd88 100644 --- a/workspace.go +++ b/workspace.go @@ -202,6 +202,7 @@ type WorkspacePermissions struct { CanUpdateVariable bool `jsonapi:"attr,can-update-variable"` } +// WSIncludeOps represents the available options for include query params. // https://www.terraform.io/docs/cloud/api/workspaces.html#available-related-resources type WSIncludeOps string @@ -221,6 +222,8 @@ const ( // WorkspaceReadOptions represents the options for reading a workspace. type WorkspaceReadOptions struct { + // Optional: A list of relations to include. + // https://www.terraform.io/docs/cloud/api/workspaces.html#available-related-resources Include []WSIncludeOps `url:"include,omitempty"` } @@ -228,13 +231,13 @@ type WorkspaceReadOptions struct { type WorkspaceListOptions struct { ListOptions - // A search string (partial workspace name) used to filter the results. + // Optional: A search string (partial workspace name) used to filter the results. Search string `url:"search[name],omitempty"` - // A search string (comma-separated tag names) used to filter the results. + // Optional: A search string (comma-separated tag names) used to filter the results. Tags string `url:"search[tags],omitempty"` - // A list of relations to include. See available resources https://www.terraform.io/docs/cloud/api/workspaces.html#available-related-resources + // Optional: A list of relations to include. See available resources https://www.terraform.io/docs/cloud/api/workspaces.html#available-related-resources Include []WSIncludeOps `url:"include,omitempty"` } @@ -246,27 +249,27 @@ type WorkspaceCreateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,workspaces"` - // Required when execution-mode is set to agent. The ID of the agent pool + // Required when: execution-mode is set to agent. The ID of the agent pool // belonging to the workspace's organization. This value must not be specified // if execution-mode is set to remote or local or if operations is set to true. AgentPoolID *string `jsonapi:"attr,agent-pool-id,omitempty"` - // Whether destroy plans can be queued on the workspace. + // Optional: Whether destroy plans can be queued on the workspace. AllowDestroyPlan *bool `jsonapi:"attr,allow-destroy-plan,omitempty"` - // Whether to automatically apply changes when a Terraform plan is successful. + // Optional: Whether to automatically apply changes when a Terraform plan is successful. AutoApply *bool `jsonapi:"attr,auto-apply,omitempty"` - // A description for the workspace. + // Optional: A description for the workspace. Description *string `jsonapi:"attr,description,omitempty"` - // Which execution mode to use. Valid values are remote, local, and agent. + // Optional: Which execution mode to use. Valid values are remote, local, and agent. // When set to local, the workspace will be used for state storage only. // This value must not be specified if operations is specified. // 'agent' execution mode is not available in Terraform Enterprise. ExecutionMode *string `jsonapi:"attr,execution-mode,omitempty"` - // Whether to filter runs based on the changed files in a VCS push. If + // Optional: Whether to filter runs based on the changed files in a VCS push. If // enabled, the working directory and trigger prefixes describe a set of // paths which must contain changes for a VCS push to trigger a run. If // disabled, any push will trigger a run. @@ -274,7 +277,7 @@ type WorkspaceCreateOptions struct { GlobalRemoteState *bool `jsonapi:"attr,global-remote-state,omitempty"` - // The legacy TFE environment to use as the source of the migration, in the + // Optional: The legacy TFE environment to use as the source of the migration, in the // form organization/environment. Omit this unless you are migrating a legacy // environment. MigrationEnvironment *string `jsonapi:"attr,migration-environment,omitempty"` @@ -354,49 +357,50 @@ type WorkspaceUpdateOptions struct { // https://jsonapi.org/format/#crud-creating Type string `jsonapi:"primary,workspaces"` - // Required when execution-mode is set to agent. The ID of the agent pool + // Required when: execution-mode is set to agent. The ID of the agent pool // belonging to the workspace's organization. This value must not be specified // if execution-mode is set to remote or local or if operations is set to true. AgentPoolID *string `jsonapi:"attr,agent-pool-id,omitempty"` - // Whether destroy plans can be queued on the workspace. + // Optional: Whether destroy plans can be queued on the workspace. AllowDestroyPlan *bool `jsonapi:"attr,allow-destroy-plan,omitempty"` - // Whether to automatically apply changes when a Terraform plan is successful. + // Optional: Whether to automatically apply changes when a Terraform plan is successful. AutoApply *bool `jsonapi:"attr,auto-apply,omitempty"` - // A new name for the workspace, which can only include letters, numbers, -, + // Optional: A new name for the workspace, which can only include letters, numbers, -, // and _. This will be used as an identifier and must be unique in the // organization. Warning: Changing a workspace's name changes its URL in the // API and UI. Name *string `jsonapi:"attr,name,omitempty"` - // A description for the workspace. + // Optional: A description for the workspace. Description *string `jsonapi:"attr,description,omitempty"` - // Which execution mode to use. Valid values are remote, local, and agent. + // Optional: Which execution mode to use. Valid values are remote, local, and agent. // When set to local, the workspace will be used for state storage only. // This value must not be specified if operations is specified. // 'agent' execution mode is not available in Terraform Enterprise. ExecutionMode *string `jsonapi:"attr,execution-mode,omitempty"` - // Whether to filter runs based on the changed files in a VCS push. If + // Optional: Whether to filter runs based on the changed files in a VCS push. If // enabled, the working directory and trigger prefixes describe a set of // paths which must contain changes for a VCS push to trigger a run. If // disabled, any push will trigger a run. FileTriggersEnabled *bool `jsonapi:"attr,file-triggers-enabled,omitempty"` + // Optional: GlobalRemoteState *bool `jsonapi:"attr,global-remote-state,omitempty"` // DEPRECATED. Whether the workspace will use remote or local execution mode. // Use ExecutionMode instead. Operations *bool `jsonapi:"attr,operations,omitempty"` - // Whether to queue all runs. Unless this is set to true, runs triggered by + // Optional: Whether to queue all runs. Unless this is set to true, runs triggered by // a webhook will not be queued until at least one run is manually queued. QueueAllRuns *bool `jsonapi:"attr,queue-all-runs,omitempty"` - // Whether this workspace allows speculative plans. Setting this to false + // Optional: Whether this workspace allows speculative plans. Setting this to false // prevents Terraform Cloud or the Terraform Enterprise instance from // running plans on pull requests, which can improve security if the VCS // repository is public or includes untrusted contributors. @@ -408,21 +412,21 @@ type WorkspaceUpdateOptions struct { // regardless of this setting. StructuredRunOutputEnabled *bool `jsonapi:"attr,structured-run-output-enabled,omitempty"` - // The version of Terraform to use for this workspace. + // Optional: The version of Terraform to use for this workspace. TerraformVersion *string `jsonapi:"attr,terraform-version,omitempty"` - // List of repository-root-relative paths which list all locations to be + // Optional: List of repository-root-relative paths which list all locations to be // tracked for changes. See FileTriggersEnabled above for more details. TriggerPrefixes []string `jsonapi:"attr,trigger-prefixes,omitempty"` - // To delete a workspace's existing VCS repo, specify null instead of an + // Optional: To delete a workspace's existing VCS repo, specify null instead of an // object. To modify a workspace's existing VCS repo, include whichever of // the keys below you wish to modify. To add a new VCS repo to a workspace // that didn't previously have one, include at least the oauth-token-id and // identifier keys. VCSRepo *VCSRepoOptions `jsonapi:"attr,vcs-repo,omitempty"` - // A relative path that Terraform will execute within. This defaults to the + // Optional: A relative path that Terraform will execute within. This defaults to the // root of your repository and is typically set to a subdirectory matching // the environment when multiple environments exist within the same // repository.