Creating a stack

unless you're defining a stack programmatically using our / /vendors/terraform/terraform provider md , you will be creating one from the root of your spacelift account you need to be an admin to create a stack by default, github account owners and admins are automatically given spacelift admin privileges, but this can be customized using /policy/login policy md and/or / /integrations/single sign on md the stack creation process involves four simple steps /#integrate vcs ; /#define behavior ; creating a stack md#configure backend (different for each supported backend, eg creating a stack md#terraform , pulumi) creating a stack md#name your stack ; please see below for a step by step walkthrough and explanation integrate vcs in the first step you will need to tell spacelift where to look for the terraform code for the stack a combination of git repository and one of its existing branches the branch that you specify set here is what we called a tracked branch by default, anything that you push to this branch will be considered for deployment anything you push to a different branch will be tested for changes against the current state a few things worth noting you can point multiple spacelift stacks to the same repository, even the same branch; the default behavior can be tweaked extensively to work with all sorts of git and deployment workflows (yes, we like monorepos, too) using /policy/git push policy md and /policy/trigger policy md policies, which are more advanced topics; in order to learn what exactly our git hosting provider integration means, please refer to / /integrations/source control/github md and / /integrations/source control/gitlab md integration documentation; if you're using our default github app integration, we only list the repositories you've given us access to if some repositories appear to be missing in the selection dropdown, it's likely that you've installed the app on a few selected repositories that's fine, too, just / /integrations/source control/github md and retry define behavior regardless of which of the supported backends (terraform, pulumi etc ) you're setting up your stack to use, there are a few common settings that apply to all of them you'll have a chance to define them in the next step the basic settings are whether the stack is /#administrative ; project root (optional), i e where inside the repository spacelift should look for the infra project source code; /worker pools md to use, if applicable; the advanced settings are whether the changes should /#autodeploy ; whether obsolete tests should be /#autoretry ; list of commands to run before project initialization; docker image to use to for your job container; configure backend at this point you'll probably know whether you want to create a creating a stack md#terraform or a creating a stack md#pulumi stack each of the supported vendors has some settings that are specific to it, and the backend configuration step is where you can define them terraform when selecting terraform , you can choose which version of terraform to start with we support terraform 0 12 0 and above you don't need to dwell on this decision since you can change the version later spacelift supports full / /vendors/terraform/version management md allowing you to even preview the impact of upgrading to a newer version the next two decisions involves your terraform state first, whether you want us to provide a terraform state backend for your state we do offer that as a convenience feature, though spacelift works just fine with any remote backend, like s3 if you want to bring your own backend, there's no point in doing additional https //www terraform io/docs/state/locking html spacelift itself provides a more sophisticated state access control mechanism than terraform if you choose not to use our state backend, feel free to proceed if you do want us to manage your state, you have an option to import an existing state file from your previous backend this is only relevant if you're migrating an existing terraform project to spacelift if you have no state yet and spacelift will be creating resources from scratch, this step is unnecessary remember this is the only time you can ask spacelift to be the state backend for a given stack, so choose wisely you can read more about state management / /vendors/terraform/state management md pulumi when creating a pulumi stack, you will need to provide two things first, the login url to your pulumi state backend, as currently we don't provide one like we do for terraform, so you will need to bring your own second, you need to specify the name of the pulumi stack this is separate from the name of the spacelift stack, which you will specify in the creating a stack md#name your stack that said, nothing prevents you from keeping them in sync name your stack we're almost there, but here comes the most difficult step naming things here's where you give your new stack a nice informative stack settings md#name and description this one even supports markdown you'll be able to change the name and description later, too with one caveat based on the original name , spacelift generates an immutable slug that serves as a unique identifier of this stack if the name and the slug diverge significantly, things may become confusing also, this is the opportunity to set a few stack settings md#labels labels are useful for searching and grouping things, but also work extremely well with policies