workspace

package
v0.3.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2025 License: MPL-2.0 Imports: 45 Imported by: 0

Documentation

Overview

templ: version: v0.3.865

Package workspace provides access to terraform workspaces

Index

Constants

View Source 
const (

	//
	// VCS trigger strategies to present to the user.
	//
	// every vcs event trigger runs
	VCSTriggerAlways string = "always"
	// only vcs events with changed files matching a set of glob patterns
	// triggers run
	VCSTriggerPatterns string = "patterns"
	// only push tag vcs events trigger runs
	VCSTriggerTags string = "tags"
)

Variables

View Source 
var (
	ErrWorkspaceAlreadyLocked         = errors.New("workspace already locked")
	ErrWorkspaceLockedByDifferentUser = errors.New("workspace locked by different user")
	ErrWorkspaceLockedByRun           = errors.New("workspace is locked by Run")
	ErrWorkspaceAlreadyUnlocked       = errors.New("workspace already unlocked")
	ErrWorkspaceUnlockDenied          = errors.New("unauthorized to unlock workspace")
	ErrWorkspaceInvalidLock           = errors.New("invalid workspace lock")
	ErrUnsupportedTerraformVersion    = errors.New("unsupported terraform version")

	ErrTagsRegexAndTriggerPatterns     = errors.New("cannot specify both tags-regex and trigger-patterns")
	ErrTagsRegexAndAlwaysTrigger       = errors.New("cannot specify both tags-regex and always-trigger")
	ErrTriggerPatternsAndAlwaysTrigger = errors.New("cannot specify both trigger-patterns and always-trigger")
	ErrInvalidTriggerPattern           = errors.New("invalid trigger glob pattern")
	ErrInvalidTagsRegex                = errors.New("invalid vcs tags regular expression")
	ErrAgentExecutionModeWithoutPool   = errors.New("agent execution mode requires agent pool ID")
	ErrNonAgentExecutionModeWithPool   = errors.New("agent pool ID can only be specified with agent execution mode")
)
View Source 
var ErrInvalidTagSpec = errors.New("invalid tag spec: must provide either an ID or a name")

Functions

func NewCommand added in v0.1.9 

func NewCommand(apiClient *otfapi.Client) *cobra.Command
func WorkspaceHeaderLinks(workspaceID resource.TfeID, canUpdate bool) templ.Component

Types

type CLI added in v0.1.9 

type CLI struct {
	// contains filtered or unexported fields
}

type Client 

type Client struct {
	*otfapi.Client
}

func (*Client) Get added in v0.2.2 

func (c *Client) Get(ctx context.Context, workspaceID resource.TfeID) (*Workspace, error)

func (*Client) GetByName added in v0.2.2 

func (c *Client) GetByName(ctx context.Context, organization organization.Name, workspace string) (*Workspace, error)

func (*Client) List added in v0.2.2 

func (c *Client) List(ctx context.Context, opts ListOptions) (*resource.Page[*Workspace], error)

func (*Client) Lock added in v0.2.2 

func (c *Client) Lock(ctx context.Context, workspaceID resource.TfeID, runID *resource.TfeID) (*Workspace, error)

func (*Client) Unlock added in v0.2.2 

func (c *Client) Unlock(ctx context.Context, workspaceID resource.TfeID, runID *resource.TfeID, force bool) (*Workspace, error)

func (*Client) Update added in v0.2.2 

func (c *Client) Update(ctx context.Context, workspaceID resource.TfeID, opts UpdateOptions) (*Workspace, error)

type ConnectOptions 

type ConnectOptions struct {
	RepoPath      *string
	VCSProviderID *resource.TfeID

	Branch        *string
	TagsRegex     *string
	AllowCLIApply *bool
}

type Connection added in v0.1.4 

type Connection struct {
	// Pushes to this VCS branch trigger runs. Empty string means the default
	// branch is used. Ignored if TagsRegex is non-empty.
	Branch string
	// Pushed tags matching this regular expression trigger runs. Mutually
	// exclusive with TriggerPatterns.
	TagsRegex string

	VCSProviderID resource.TfeID
	Repo          string

	// By default, once a workspace is connected to a repo it is not
	// possible to run a terraform apply via the CLI. Setting this to true
	// overrides this behaviour.
	AllowCLIApply bool
}

type CreateOptions 

type CreateOptions struct {
	AgentPoolID                *resource.TfeID
	AllowDestroyPlan           *bool
	AutoApply                  *bool
	Description                *string
	ExecutionMode              *ExecutionMode
	GlobalRemoteState          *bool
	MigrationEnvironment       *string
	Name                       *string
	QueueAllRuns               *bool
	SpeculativeEnabled         *bool
	SourceName                 *string
	SourceURL                  *string
	StructuredRunOutputEnabled *bool
	Tags                       []TagSpec
	Engine                     *engine.Engine
	EngineVersion              *Version
	TriggerPrefixes            []string
	TriggerPatterns            []string
	WorkingDirectory           *string
	Organization               *organization.Name

	// Always trigger runs. A value of true is mutually exclusive with
	// setting TriggerPatterns or ConnectOptions.TagsRegex.
	AlwaysTrigger *bool

	*ConnectOptions
}

CreateOptions represents the options for creating a new workspace.

type Event added in v0.3.23 

type Event struct {
	ID           resource.TfeID    `json:"workspace_id"`
	LatestRunID  *resource.TfeID   `json:"latest_run_id"`
	Organization organization.Name `json:"organization_name"`
	LockUsername *user.Username    `json:"lock_username"`
	LockRunID    *resource.TfeID   `json:"lock_run_id"`
}

func (Event) GetID added in v0.3.23 

func (e Event) GetID() resource.TfeID

func (Event) Lock added in v0.3.23 

func (e Event) Lock() resource.ID

func (Event) Locked added in v0.3.23 

func (e Event) Locked() bool

type ExecutionMode 

type ExecutionMode string
const (
	RemoteExecutionMode ExecutionMode = "remote"
	LocalExecutionMode  ExecutionMode = "local"
	AgentExecutionMode  ExecutionMode = "agent"

	DefaultAllowDestroyPlan = true
)

func ExecutionModePtr 

func ExecutionModePtr(m ExecutionMode) *ExecutionMode

ExecutionModePtr returns a pointer to an execution mode.

type FakeService added in v0.2.2 

type FakeService struct {
	Workspaces []*Workspace
	Policy     Policy
}

func (*FakeService) AddTags added in v0.2.2 

func (f *FakeService) AddTags(ctx context.Context, workspaceID resource.TfeID, tags []TagSpec) error

func (*FakeService) Create added in v0.2.2 

func (f *FakeService) Create(context.Context, CreateOptions) (*Workspace, error)

func (*FakeService) Delete added in v0.2.2 

func (f *FakeService) Delete(context.Context, resource.TfeID) (*Workspace, error)

func (*FakeService) Get added in v0.2.2 

func (f *FakeService) Get(context.Context, resource.TfeID) (*Workspace, error)

func (*FakeService) GetByName added in v0.2.2 

func (f *FakeService) GetByName(context.Context, organization.Name, string) (*Workspace, error)

func (*FakeService) GetWorkspacePolicy added in v0.3.6 

func (f *FakeService) GetWorkspacePolicy(context.Context, resource.TfeID) (Policy, error)

func (*FakeService) List added in v0.2.2 

func (f *FakeService) List(ctx context.Context, opts ListOptions) (*resource.Page[*Workspace], error)

func (*FakeService) ListConnectedWorkspaces added in v0.2.2 

func (f *FakeService) ListConnectedWorkspaces(ctx context.Context, vcsProviderID resource.TfeID, repoPath string) ([]*Workspace, error)

func (*FakeService) ListTags added in v0.2.2 

func (f *FakeService) ListTags(context.Context, organization.Name, ListTagsOptions) (*resource.Page[*Tag], error)

func (*FakeService) Lock added in v0.2.2 

func (f *FakeService) Lock(context.Context, resource.TfeID, *resource.TfeID) (*Workspace, error)

func (*FakeService) RemoveTags added in v0.2.2 

func (f *FakeService) RemoveTags(ctx context.Context, workspaceID resource.TfeID, tags []TagSpec) error

func (*FakeService) SetPermission added in v0.2.2 

func (f *FakeService) SetPermission(ctx context.Context, workspaceID, teamID resource.TfeID, role authz.Role) error

func (*FakeService) Unlock added in v0.2.2 

func (f *FakeService) Unlock(context.Context, resource.TfeID, *resource.TfeID, bool) (*Workspace, error)

func (*FakeService) UnsetPermission added in v0.2.2 

func (f *FakeService) UnsetPermission(ctx context.Context, workspaceID, teamID resource.TfeID) error

func (*FakeService) Update added in v0.2.2 

func (f *FakeService) Update(_ context.Context, _ resource.TfeID, opts UpdateOptions) (*Workspace, error)

func (*FakeService) Watch added in v0.3.23 

func (f *FakeService) Watch(context.Context) (<-chan pubsub.Event[*Event], func())

type LatestRun 

type LatestRun struct {
	ID     resource.TfeID
	Status runstatus.Status
}

LatestRun is a summary of the latest run for a workspace

type ListOptions 

type ListOptions struct {
	Search       string             `schema:"search[name]"`
	Tags         []string           `schema:"search[tags]"`
	Status       []runstatus.Status `schema:"search[status]"`
	Organization *organization.Name `schema:"organization_name"`

	resource.PageOptions
}

ListOptions are options for paginating and filtering a list of Workspaces

type ListTagsOptions 

type ListTagsOptions struct {
	resource.PageOptions
}

ListTagsOptions are options for paginating and filtering a list of tags

type ListWorkspaceTagsOptions 

type ListWorkspaceTagsOptions struct {
	resource.PageOptions
}

ListWorkspaceTagsOptions are options for paginating and filtering a list of workspace tags

type Options 

type Options struct {
	*sql.DB
	*sql.Listener
	*tfeapi.Responder
	*authz.Authorizer

	logr.Logger

	OrganizationService *organization.Service
	VCSProviderService  *vcsprovider.Service
	TeamService         *team.Service
	UserService         *user.Service
	ConnectionService   *connections.Service
	DefaultEngine       *engine.Engine
	EngineService       *engine.Service
}

type Permission added in v0.3.17 

type Permission struct {
	TeamID resource.TfeID
	Role   authz.Role
}

Permission binds a role to a team.

type Policy added in v0.3.17 

type Policy struct {
	Permissions []Permission
	// contains filtered or unexported fields
}

func (Policy) Check added in v0.3.17 

func (p Policy) Check(subject resource.ID, action authz.Action) bool

Check whether the subject is allowed to carry out the given action on the workspace belonging to the policy.

type Service 

type Service struct {
	logr.Logger
	*authz.Authorizer
	// contains filtered or unexported fields
}

func NewService 

func NewService(opts Options) *Service

func (*Service) AddHandlers added in v0.2.2 

func (s *Service) AddHandlers(r *mux.Router)

func (*Service) AddTags added in v0.2.2 

func (s *Service) AddTags(ctx context.Context, workspaceID resource.TfeID, tags []TagSpec) error

func (*Service) AfterCreateWorkspace added in v0.1.8 

func (s *Service) AfterCreateWorkspace(hook func(context.Context, *Workspace) error)

func (*Service) BeforeCreateWorkspace added in v0.2.0 

func (s *Service) BeforeCreateWorkspace(hook func(context.Context, *Workspace) error)

func (*Service) BeforeUpdateWorkspace added in v0.2.0 

func (s *Service) BeforeUpdateWorkspace(hook func(context.Context, *Workspace) error)

func (*Service) Create added in v0.2.2 

func (s *Service) Create(ctx context.Context, opts CreateOptions) (*Workspace, error)

func (*Service) Delete added in v0.2.2 

func (s *Service) Delete(ctx context.Context, workspaceID resource.TfeID) (*Workspace, error)

func (*Service) DeleteTags added in v0.2.2 

func (s *Service) DeleteTags(ctx context.Context, organization organization.Name, tagIDs []resource.TfeID) error

func (*Service) Get added in v0.2.2 

func (s *Service) Get(ctx context.Context, workspaceID resource.TfeID) (*Workspace, error)

func (*Service) GetByName added in v0.2.2 

func (s *Service) GetByName(ctx context.Context, organization organization.Name, workspace string) (*Workspace, error)

func (*Service) GetWorkspacePolicy added in v0.3.6 

func (s *Service) GetWorkspacePolicy(ctx context.Context, workspaceID resource.TfeID) (Policy, error)

GetWorkspacePolicy retrieves the authorization policy for a workspace.

NOTE: there is no auth because it is used in the process of making an auth decision.

func (*Service) List added in v0.2.2 

func (s *Service) List(ctx context.Context, opts ListOptions) (*resource.Page[*Workspace], error)

func (*Service) ListConnectedWorkspaces added in v0.1.14 

func (s *Service) ListConnectedWorkspaces(ctx context.Context, vcsProviderID resource.TfeID, repoPath string) ([]*Workspace, error)

func (*Service) ListTags added in v0.2.2 

func (s *Service) ListTags(ctx context.Context, organization organization.Name, opts ListTagsOptions) (*resource.Page[*Tag], error)

func (*Service) ListWorkspaceTags added in v0.2.2 

func (s *Service) ListWorkspaceTags(ctx context.Context, workspaceID resource.TfeID, opts ListWorkspaceTagsOptions) (*resource.Page[*Tag], error)

func (*Service) Lock added in v0.2.2 

func (s *Service) Lock(ctx context.Context, workspaceID resource.TfeID, runID *resource.TfeID) (*Workspace, error)

Lock locks the workspace. A workspace can only be locked on behalf of a run or a user. If the former then runID must be populated. Otherwise a user is extracted from the context.

func (Service) NewWorkspace added in v0.3.20 

func (f Service) NewWorkspace(ctx context.Context, opts CreateOptions) (*Workspace, error)

func (*Service) RemoveTags added in v0.2.2 

func (s *Service) RemoveTags(ctx context.Context, workspaceID resource.TfeID, tags []TagSpec) error

func (*Service) SetLatestRun added in v0.3.10 

func (s *Service) SetLatestRun(ctx context.Context, workspaceID, runID resource.TfeID) (*Workspace, error)

SetLatestRun sets the latest run for the workspace

func (*Service) SetPermission added in v0.2.2 

func (s *Service) SetPermission(ctx context.Context, workspaceID, teamID resource.TfeID, role authz.Role) error

func (*Service) TagWorkspaces added in v0.2.2 

func (s *Service) TagWorkspaces(ctx context.Context, tagID resource.TfeID, workspaceIDs []resource.TfeID) error

func (*Service) Unlock added in v0.2.2 

func (s *Service) Unlock(ctx context.Context, workspaceID resource.TfeID, runID *resource.TfeID, force bool) (*Workspace, error)

Unlock unlocks the workspace. A workspace can only be unlocked on behalf of a run or a user. If the former then runID must be non-nil; otherwise a user is extracted from the context.

func (*Service) UnsetPermission added in v0.2.2 

func (s *Service) UnsetPermission(ctx context.Context, workspaceID, teamID resource.TfeID) error

func (*Service) Update added in v0.2.2 

func (s *Service) Update(ctx context.Context, workspaceID resource.TfeID, opts UpdateOptions) (*Workspace, error)

func (*Service) Watch added in v0.2.2 

func (s *Service) Watch(ctx context.Context) (<-chan pubsub.Event[*Event], func())

type TFEOrganizationTag added in v0.3.17 

type TFEOrganizationTag struct {
	ID resource.TfeID `jsonapi:"primary,tags"`

	// Optional:
	Name string `jsonapi:"attribute" json:"name,omitempty"`

	// Optional: Number of workspaces that have this tag
	InstanceCount int `jsonapi:"attribute" json:"instance-count,omitempty"`

	// The org this tag belongs to
	Organization *organization.TFEOrganization `jsonapi:"relationship" json:"organization"`
}

TFEOrganizationTag represents a Terraform Enterprise Organization tag

type TFERun added in v0.3.17 

type TFERun struct {
	ID resource.TfeID `jsonapi:"primary,runs"`
}

type TFETag added in v0.3.17 

type TFETag struct {
	ID   *resource.TfeID `jsonapi:"primary,tags"`
	Name string          `jsonapi:"attribute" json:"name,omitempty"`
}

Tag is owned by an organization and applied to workspaces. Used for grouping and search. Only one of ID or name must be specified.

func (*TFETag) UnmarshalID added in v0.3.17 

func (t *TFETag) UnmarshalID(id string) error

UnmarshalID helps datadog/jsonapi to unmarshal the ID in a serialized tag - either the ID or the name is set, and datadog/jsonapi otherwise gets upset when ID is unset.

type TFEVCSRepo added in v0.3.17 

type TFEVCSRepo struct {
	Branch            string         `json:"branch"`
	DisplayIdentifier string         `json:"display-identifier"`
	Identifier        string         `json:"identifier"`
	IngressSubmodules bool           `json:"ingress-submodules"`
	OAuthTokenID      resource.TfeID `json:"oauth-token-id"`
	RepositoryHTTPURL string         `json:"repository-http-url"`
	TagsRegex         string         `json:"tags-regex"`
	ServiceProvider   string         `json:"service-provider"`
}

TFEVCSRepo contains the configuration of a VCS integration.

type TFEVCSRepoOptions added in v0.3.17 

type TFEVCSRepoOptions struct {
	Branch            *string         `json:"branch,omitempty"`
	Identifier        *string         `json:"identifier,omitempty"`
	IngressSubmodules *bool           `json:"ingress-submodules,omitempty"`
	OAuthTokenID      *resource.TfeID `json:"oauth-token-id,omitempty"`
	TagsRegex         *string         `json:"tags-regex,omitempty"`
}

TFEVCSRepoOptions is used by workspaces, policy sets, and registry modules TFEVCSRepoOptions represents the configuration options of a VCS integration.

type TFEWorkspace added in v0.3.17 

type TFEWorkspace struct {
	ID                         resource.TfeID           `jsonapi:"primary,workspaces"`
	Actions                    *TFEWorkspaceActions     `jsonapi:"attribute" json:"actions"`
	AgentPoolID                *resource.TfeID          `jsonapi:"attribute" json:"agent-pool-id"`
	AllowDestroyPlan           bool                     `jsonapi:"attribute" json:"allow-destroy-plan"`
	AutoApply                  bool                     `jsonapi:"attribute" json:"auto-apply"`
	CanQueueDestroyPlan        bool                     `jsonapi:"attribute" json:"can-queue-destroy-plan"`
	CreatedAt                  time.Time                `jsonapi:"attribute" json:"created-at"`
	Description                string                   `jsonapi:"attribute" json:"description"`
	Environment                string                   `jsonapi:"attribute" json:"environment"`
	ExecutionMode              string                   `jsonapi:"attribute" json:"execution-mode"`
	FileTriggersEnabled        bool                     `jsonapi:"attribute" json:"file-triggers-enabled"`
	GlobalRemoteState          bool                     `jsonapi:"attribute" json:"global-remote-state"`
	Locked                     bool                     `jsonapi:"attribute" json:"locked"`
	MigrationEnvironment       string                   `jsonapi:"attribute" json:"migration-environment"`
	Name                       string                   `jsonapi:"attribute" json:"name"`
	Operations                 bool                     `jsonapi:"attribute" json:"operations"`
	Permissions                *TFEWorkspacePermissions `jsonapi:"attribute" json:"permissions"`
	QueueAllRuns               bool                     `jsonapi:"attribute" json:"queue-all-runs"`
	SpeculativeEnabled         bool                     `jsonapi:"attribute" json:"speculative-enabled"`
	SourceName                 string                   `jsonapi:"attribute" json:"source-name"`
	SourceURL                  string                   `jsonapi:"attribute" json:"source-url"`
	StructuredRunOutputEnabled bool                     `jsonapi:"attribute" json:"structured-run-output-enabled"`
	TerraformVersion           *Version                 `jsonapi:"attribute" json:"terraform-version"`
	TriggerPrefixes            []string                 `jsonapi:"attribute" json:"trigger-prefixes"`
	TriggerPatterns            []string                 `jsonapi:"attribute" json:"trigger-patterns"`
	VCSRepo                    *TFEVCSRepo              `jsonapi:"attribute" json:"vcs-repo"`
	WorkingDirectory           string                   `jsonapi:"attribute" json:"working-directory"`
	UpdatedAt                  time.Time                `jsonapi:"attribute" json:"updated-at"`
	ResourceCount              int                      `jsonapi:"attribute" json:"resource-count"`
	ApplyDurationAverage       time.Duration            `jsonapi:"attribute" json:"apply-duration-average"`
	PlanDurationAverage        time.Duration            `jsonapi:"attribute" json:"plan-duration-average"`
	PolicyCheckFailures        int                      `jsonapi:"attribute" json:"policy-check-failures"`
	RunFailures                int                      `jsonapi:"attribute" json:"run-failures"`
	RunsCount                  int                      `jsonapi:"attribute" json:"workspace-kpis-runs-count"`
	TagNames                   []string                 `jsonapi:"attribute" json:"tag-names"`

	// Relations
	CurrentRun   *TFERun                       `jsonapi:"relationship" json:"current-run"`
	Organization *organization.TFEOrganization `jsonapi:"relationship" json:"organization"`
	Outputs      []*TFEWorkspaceOutput         `jsonapi:"relationship" json:"outputs"`
}

TFEWorkspace represents a Terraform Enterprise workspace.

func ToTFE added in v0.3.17 

func ToTFE(a *authz.Authorizer, from *Workspace, r *http.Request) (*TFEWorkspace, error)

ToTFE converts an OTF workspace to a TFE workspace.

type TFEWorkspaceActions added in v0.3.17 

type TFEWorkspaceActions struct {
	IsDestroyable bool `json:"is-destroyable"`
}

TFEWorkspaceActions represents the workspace actions.

type TFEWorkspaceCreateOptions added in v0.3.17 

type TFEWorkspaceCreateOptions struct {
	// Type is a public field utilized by JSON:API to set the resource type via
	// the field tag.  It is not a user-defined value and does not need to be
	// set.  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
	// 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 *resource.TfeID `jsonapi:"attribute" json:"agent-pool-id,omitempty"`

	// Whether destroy plans can be queued on the workspace.
	AllowDestroyPlan *bool `jsonapi:"attribute" json:"allow-destroy-plan,omitempty"`

	// Whether to automatically apply changes when a Terraform plan is successful.
	AutoApply *bool `jsonapi:"attribute" json:"auto-apply,omitempty"`

	// A description for the workspace.
	Description *string `jsonapi:"attribute" json:"description,omitempty"`

	// 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:"attribute" json:"execution-mode,omitempty"`

	// 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:"attribute" json:"file-triggers-enabled,omitempty"`

	GlobalRemoteState *bool `jsonapi:"attribute" json:"global-remote-state,omitempty"`

	// 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:"attribute" json:"migration-environment,omitempty"`

	// The name of the workspace, which can only include letters, numbers, -,
	// and _. This will be used as an identifier and must be unique in the
	// organization.
	Name *string `jsonapi:"attribute" json:"name"`

	// DEPRECATED. Whether the workspace will use remote or local execution mode.
	// Use ExecutionMode instead.
	Operations *bool `jsonapi:"attribute" json:"operations,omitempty"`

	// Organization the workspace belongs to. Required.
	Organization *organization.Name `schema:"organization_name"`

	// 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:"attribute" json:"queue-all-runs,omitempty"`

	// 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.
	SpeculativeEnabled *bool `jsonapi:"attribute" json:"speculative-enabled,omitempty"`

	// BETA. A friendly name for the application or client creating this
	// workspace. If set, this will be displayed on the workspace as
	// "Created via <SOURCE NAME>".
	SourceName *string `jsonapi:"attribute" json:"source-name,omitempty"`

	// BETA. A URL for the application or client creating this workspace. This
	// can be the URL of a related resource in another app, or a link to
	// documentation or other info about the client.
	SourceURL *string `jsonapi:"attribute" json:"source-url,omitempty"`

	// BETA. Enable the experimental advanced run user interface.
	// This only applies to runs using Terraform version 0.15.2 or newer,
	// and runs executed using older versions will see the classic experience
	// regardless of this setting.
	StructuredRunOutputEnabled *bool `jsonapi:"attribute" json:"structured-run-output-enabled,omitempty"`

	// The version of Terraform to use for this workspace. Upon creating a
	// workspace, the latest version is selected unless otherwise specified.
	TerraformVersion *Version `jsonapi:"attribute" json:"terraform-version,omitempty" schema:"terraform_version"`

	// List of repository-root-relative paths which list all locations to be
	// tracked for changes. See FileTriggersEnabled above for more details.
	TriggerPrefixes []string `jsonapi:"attribute" json:"trigger-prefixes,omitempty"`

	// Optional: List of patterns used to match against changed files in order
	// to decide whether to trigger a run or not.
	TriggerPatterns []string `jsonapi:"attribute" json:"trigger-patterns,omitempty"`

	// Settings for the workspace's VCS repository. If omitted, the workspace is
	// created without a VCS repo. If included, you must specify at least the
	// oauth-token-id and identifier keys below.
	VCSRepo *TFEVCSRepoOptions `jsonapi:"attribute" json:"vcs-repo,omitempty"`

	// 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.
	WorkingDirectory *string `jsonapi:"attribute" json:"working-directory,omitempty"`

	// A list of tags to attach to the workspace. If the tag does not already
	// exist, it is created and added to the workspace.
	Tags []*TFETag `jsonapi:"relationship" json:"tags,omitempty"`
}

TFEWorkspaceCreateOptions represents the options for creating a new workspace.

type TFEWorkspaceList added in v0.3.17 

type TFEWorkspaceList struct {
	*types.Pagination
	Items []*Workspace
}

TFEWorkspaceList represents a list of workspaces.

type TFEWorkspaceListOptions added in v0.3.17 

type TFEWorkspaceListOptions struct {
	types.ListOptions

	// Optional: A search string (partial workspace name) used to filter the results.
	Search string `schema:"search[name],omitempty"`

	// Optional: A search string (comma-separated tag names) used to filter the results.
	Tags string `schema:"search[tags],omitempty"`

	// Optional: A search string (comma-separated tag names to exclude) used to filter the results.
	ExcludeTags string `schema:"search[exclude-tags],omitempty"`

	// Optional: A search on substring matching to filter the results.
	WildcardName string `schema:"search[wildcard-name],omitempty"`

	// Optional: A filter string to list all the workspaces linked to a given project id in the organization.
	ProjectID resource.TfeID `schema:"filter[project][id],omitempty"`
}

TFEWorkspaceListOptions represents the options for listing workspaces.

type TFEWorkspaceOutput added in v0.3.17 

type TFEWorkspaceOutput struct {
	ID        resource.TfeID `jsonapi:"primary,workspace-outputs"`
	Name      string         `jsonapi:"attribute" json:"name"`
	Sensitive bool           `jsonapi:"attribute" json:"sensitive"`
	Type      string         `jsonapi:"attribute" json:"output-type"`
	Value     any            `jsonapi:"attribute" json:"value"`
}

type TFEWorkspacePermissions added in v0.3.17 

type TFEWorkspacePermissions struct {
	CanDestroy        bool `json:"can-destroy"`
	CanForceUnlock    bool `json:"can-force-unlock"`
	CanLock           bool `json:"can-lock"`
	CanQueueApply     bool `json:"can-queue-apply"`
	CanQueueDestroy   bool `json:"can-queue-destroy"`
	CanQueueRun       bool `json:"can-queue-run"`
	CanReadSettings   bool `json:"can-read-settings"`
	CanUnlock         bool `json:"can-unlock"`
	CanUpdate         bool `json:"can-update"`
	CanUpdateVariable bool `json:"can-update-variable"`
}

TFEWorkspacePermissions represents the workspace permissions.

type TFEWorkspaceUpdateOptions added in v0.3.17 

type TFEWorkspaceUpdateOptions struct {
	// Type is a public field utilized by JSON:API to set the resource type via
	// the field tag.  It is not a user-defined value and does not need to be
	// set.  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
	// 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 *resource.TfeID `jsonapi:"attribute" json:"agent-pool-id,omitempty"`

	// Whether destroy plans can be queued on the workspace.
	AllowDestroyPlan *bool `jsonapi:"attribute" json:"allow-destroy-plan,omitempty"`

	// Whether to automatically apply changes when a Terraform plan is successful.
	AutoApply *bool `jsonapi:"attribute" json:"auto-apply,omitempty"`

	// 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:"attribute" json:"name,omitempty"`

	// A description for the workspace.
	Description *string `jsonapi:"attribute" json:"description,omitempty"`

	// 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:"attribute" json:"execution-mode,omitempty" schema:"execution_mode"`

	// 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:"attribute" json:"file-triggers-enabled,omitempty"`

	GlobalRemoteState *bool `jsonapi:"attribute" json:"global-remote-state,omitempty"`

	// DEPRECATED. Whether the workspace will use remote or local execution mode.
	// Use ExecutionMode instead.
	Operations *bool `jsonapi:"attribute" json:"operations,omitempty"`

	// 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:"attribute" json:"queue-all-runs,omitempty"`

	// 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.
	SpeculativeEnabled *bool `jsonapi:"attribute" json:"speculative-enabled,omitempty"`

	// BETA. Enable the experimental advanced run user interface.
	// This only applies to runs using Terraform version 0.15.2 or newer,
	// and runs executed using older versions will see the classic experience
	// regardless of this setting.
	StructuredRunOutputEnabled *bool `jsonapi:"attribute" json:"structured-run-output-enabled,omitempty"`

	// The version of Terraform to use for this workspace.
	TerraformVersion *Version `jsonapi:"attribute" json:"terraform-version,omitempty" schema:"terraform_version"`

	// List of repository-root-relative paths which list all locations to be
	// tracked for changes. See FileTriggersEnabled above for more details.
	TriggerPrefixes []string `jsonapi:"attribute" json:"trigger-prefixes,omitempty"`

	// Optional: List of patterns used to match against changed files in order
	// to decide whether to trigger a run or not.
	TriggerPatterns []string `jsonapi:"attribute" json:"trigger-patterns,omitempty"`

	// 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 VCSRepoOptionsJSON `jsonapi:"attribute" json:"vcs-repo,omitempty"`

	// 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.
	WorkingDirectory *string `jsonapi:"attribute" json:"working-directory,omitempty"`
}

TFEWorkspaceUpdateOptions represents the options for updating a workspace.

func (*TFEWorkspaceUpdateOptions) Validate added in v0.3.17 

func (opts *TFEWorkspaceUpdateOptions) Validate() error

type Tag 

type Tag struct {
	ID            resource.TfeID    // ID of the form 'tag-*'. Globally unique.
	Name          string            // Meaningful symbol. Unique to an organization.
	InstanceCount int               // Number of workspaces that have this tag
	Organization  organization.Name // Organization this tag belongs to.
}

Tag is a symbol associated with one or more workspaces. Helps searching and grouping workspaces.

type TagSpec 

type TagSpec struct {
	ID   *resource.TfeID
	Name string
}

TagSpec specifies a tag. Either ID or Name must be non-nil for it to be valid.

func (TagSpec) Valid 

func (s TagSpec) Valid() error

type TagSpecs 

type TagSpecs []TagSpec

func (TagSpecs) LogValue 

func (specs TagSpecs) LogValue() slog.Value

type UpdateOptions 

type UpdateOptions struct {
	AgentPoolID                *resource.TfeID `json:"agent-pool-id,omitempty"`
	AllowDestroyPlan           *bool
	AutoApply                  *bool
	Name                       *string
	Description                *string
	ExecutionMode              *ExecutionMode `json:"execution-mode,omitempty"`
	GlobalRemoteState          *bool
	Operations                 *bool
	QueueAllRuns               *bool
	SpeculativeEnabled         *bool
	StructuredRunOutputEnabled *bool
	EngineVersion              *Version
	TriggerPrefixes            []string
	TriggerPatterns            []string
	WorkingDirectory           *string
	Engine                     *engine.Engine

	// Always trigger runs. A value of true is mutually exclusive with
	// setting TriggerPatterns or ConnectOptions.TagsRegex.
	AlwaysTrigger *bool

	// Disconnect workspace from repo. It is invalid to specify true for an
	// already disconnected workspace.
	Disconnect bool

	// Specifying ConnectOptions either connects a currently
	// disconnected workspace, or modifies a connection if already
	// connected.
	*ConnectOptions
}

type VCSRepoOptionsJSON added in v0.3.17 

type VCSRepoOptionsJSON struct {
	TFEVCSRepoOptions

	Valid bool `json:"-"`
	Set   bool `json:"-"`
}

VCSRepoOptionsJSON wraps VCSRepoOptions and implements json.Unmarshaler in order to differentiate between VCSRepoOptions having been explicitly to null, and omitted.

NOTE: Credit to https://www.calhoun.io/how-to-determine-if-a-json-key-has-been-set-to-null-or-not-provided/

func (*VCSRepoOptionsJSON) UnmarshalJSON added in v0.3.17 

func (o *VCSRepoOptionsJSON) UnmarshalJSON(data []byte) error

UnmarshalJSON differentiates between VCSRepoOptions having been explicitly set to null by the client, or the client has left it out.

type VCSTriggerStrategy added in v0.1.4 

type VCSTriggerStrategy string

VCS trigger strategy determines which VCS events trigger runs

type Version added in v0.3.21 

type Version struct {
	// Latest if true means runs use the Latest available version at time of
	// creation of the run.
	Latest bool
	// contains filtered or unexported fields
}

Version is a workspace's engine version.

func (*Version) MarshalText added in v0.3.21 

func (v *Version) MarshalText() ([]byte, error)

func (*Version) Scan added in v0.3.21 

func (v *Version) Scan(text any) error

func (*Version) String added in v0.3.21 

func (v *Version) String() string

func (*Version) UnmarshalText added in v0.3.21 

func (v *Version) UnmarshalText(text []byte) error

func (*Version) Value added in v0.3.21 

func (v *Version) Value() (driver.Value, error)

type Workspace 

type Workspace struct {
	ID                         resource.TfeID    `jsonapi:"primary,workspaces"`
	CreatedAt                  time.Time         `jsonapi:"attribute" json:"created_at"`
	UpdatedAt                  time.Time         `jsonapi:"attribute" json:"updated_at"`
	AgentPoolID                *resource.TfeID   `jsonapi:"attribute" json:"agent-pool-id"`
	AllowDestroyPlan           bool              `jsonapi:"attribute" json:"allow_destroy_plan"`
	AutoApply                  bool              `jsonapi:"attribute" json:"auto_apply"`
	CanQueueDestroyPlan        bool              `jsonapi:"attribute" json:"can_queue_destroy_plan"`
	Description                string            `jsonapi:"attribute" json:"description"`
	Environment                string            `jsonapi:"attribute" json:"environment"`
	ExecutionMode              ExecutionMode     `jsonapi:"attribute" json:"execution_mode"`
	GlobalRemoteState          bool              `jsonapi:"attribute" json:"global_remote_state"`
	MigrationEnvironment       string            `jsonapi:"attribute" json:"migration_environment"`
	Name                       string            `jsonapi:"attribute" json:"name"`
	QueueAllRuns               bool              `jsonapi:"attribute" json:"queue_all_runs"`
	SpeculativeEnabled         bool              `jsonapi:"attribute" json:"speculative_enabled"`
	StructuredRunOutputEnabled bool              `jsonapi:"attribute" json:"structured_run_output_enabled"`
	SourceName                 string            `jsonapi:"attribute" json:"source_name"`
	SourceURL                  string            `jsonapi:"attribute" json:"source_url"`
	WorkingDirectory           string            `jsonapi:"attribute" json:"working_directory"`
	Organization               organization.Name `jsonapi:"attribute" json:"organization"`
	LatestRun                  *LatestRun        `jsonapi:"attribute" json:"latest_run"`
	Tags                       []string          `jsonapi:"attribute" json:"tags"`
	Lock                       resource.ID       `json:"-"`
	Engine                     *engine.Engine    `jsonapi:"attribute" json:"engine"`
	EngineVersion              *Version          `jsonapi:"attribute" json:"engine_version"`

	// VCS Connection; nil means the workspace is not connected.
	Connection *Connection

	// TriggerPatterns is mutually exclusive with Connection.TagsRegex.
	//
	// Note: TriggerPatterns ought to belong in Connection but it is included at
	// the root of Workspace because the go-tfe integration tests set
	// this field without setting the connection!
	TriggerPatterns []string

	// TriggerPrefixes exists only to pass the go-tfe integration tests and
	// is not used when determining whether to trigger runs. Use
	// TriggerPatterns instead.
	TriggerPrefixes []string
}

Workspace is a terraform workspace.

func NewTestWorkspace added in v0.3.20 

func NewTestWorkspace(t *testing.T, opts *CreateOptions) *Workspace

func (*Workspace) Enlock 

func (ws *Workspace) Enlock(id resource.ID) error

Enlock locks the workspace with the given ID. The ID must be either a run or user ID.

func (*Workspace) ExecutionModes 

func (ws *Workspace) ExecutionModes() []string

ExecutionModes returns a list of possible execution modes

func (*Workspace) Locked 

func (ws *Workspace) Locked() bool

func (*Workspace) LogValue 

func (ws *Workspace) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*Workspace) String 

func (ws *Workspace) String() string

func (*Workspace) Unlock 

func (ws *Workspace) Unlock(id resource.ID, force bool) error

Unlock the workspace with the given ID. The ID must be either a run or user ID.

func (*Workspace) Update 

func (ws *Workspace) Update(opts UpdateOptions) (*bool, error)

Update updates the workspace with the given options. A boolean is returned to indicate whether the workspace is to be connected to a repo (true), disconnected from a repo (false), or neither (nil).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.