Spacelift

https://docs.spacelift.io/
Admin
Spacelift is a specialized infrastructure as code (IaC) platform that automates, secures, and...
Tokens:1,095,809
Snippets:7,874
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Installer confirmation prompt

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/install

Example output when running the installer, showing the version and AWS account ID, and the confirmation prompt requiring 'yes'.

```bash
./install.sh
[2023-01-24T12:17:52+0000] INFO: installing version v0.0.6 of Spacelift into AWS account 123456789012

Are you sure you want to continue? Only 'yes' will be accepted: yes
```

--------------------------------

### Run installer to complete DR setup

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/disaster-recovery

After updating the config file, run the installer again to apply the S3 replication configuration and complete the disaster recovery setup.

```bash
./install.sh -c config.json
```

--------------------------------

### Flow YAML Configuration with Slack App Installation

Source: https://docs.spacelift.io/flows/automating-flows/flows-tf-provider

Example YAML definition for a Flow that listens for Slack mentions and responds with a hello message. The `appInstallations` section defines the Slack app installation, and blocks reference it by name. The YAML only manages the configuration layer, not lifecycle confirmations.

```yaml
appInstallations:
  slack:
    appName: Slack
    appVersion: 0.2.2
    id: 019a4a1d-3494-758a-9df9-67d6e5f4660b
blocks:
  - name: Mentions
    type:
      appBlock:
        block: appMentionSubscription
        appInstallation: slack
    position: [116, 0]
  - name: Is Hello Command
    description: Checks if the mention contains a hello command
    type:
      coreBlock: condition
    position: [0, 160]
    inputs:
      default:
        links:
          - block: Mentions
            output: default
        config:
          condition: !expr /^<@U\w+>\s+hello$/i.test(outputs.mentions.text.trim())
  - name: Hello Response
    description: Sends a hello message to the user
    type:
      appBlock:
        block: sendTextMessage
        appInstallation: slack
    position: [0, 293]
    inputs:
      default:
        links:
          - block: Is Hello Command
            output: then
        config:
          channelId: !expr outputs.mentions.channel
          text: !expr '`Hello <@${outputs.mentions.user}>!`'
          threadTs: !expr outputs.mentions.thread_ts || outputs.mentions.ts
```

--------------------------------

### Manual Setup: Export Mount and Start Launcher

Source: https://docs.spacelift.io/concepts/worker-pools/docker-based-workers

Manually exports the SPACELIFT_WORKER_EXTRA_MOUNTS variable to mount the custom CA bundle and starts the launcher. The bundle must be copied to the worker host first, e.g., to /etc/spacelift/custom-ca-bundle.crt.

```bash
export SPACELIFT_WORKER_EXTRA_MOUNTS="/etc/spacelift/custom-ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt"
./spacelift-launcher
```

--------------------------------

### Run installer with configuration file

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/install

Command to run the installer with an optional configuration file path using the -c flag.

```bash
./install.sh [-c "<configuration file>"]
```

--------------------------------

### Example IoT Endpoint Output

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/advanced-installations

Example JSON output from the describe-endpoint command, showing the endpoint address to use for DNS setup.

```json
{
    "endpointAddress": "b2mdsfpsxca6rx-ats.iot.us-east-1.amazonaws.com"
}
```

--------------------------------

### Example: Simple Delay

Source: https://docs.spacelift.io/flows/developers/building-apps/events

A complete example showing how to create a pending event, set a timer, and complete the pending event in the timer handler. The pending event includes a predicted payload with the start time and a status description.

```javascript
{
  inputs: {
    default: {
      onEvent: async ({ event }) => {
        const pendingId = await events.createPending({
          event: { startedAt: Date.now() },
          statusDescription: "Sleeping...",
        });

        await timers.block.set(event.inputConfig.seconds, {
          pendingEventId: pendingId,
        });
      },
    },
  },
  onTimer: async ({ timer }) => {
    await events.completePending(timer.pendingEvent.id);
  },
}
```

--------------------------------

### Install liftoff release candidate with Homebrew

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Installs a release candidate of liftoff via a separate Homebrew cask. This is required to get a pre-release version, as the stable cask never provides candidates.

```bash
brew install spacelift-solutions/tap/liftoff-rc
```

--------------------------------

### Referencing Secrets in App Installation Configurations

Source: https://docs.spacelift.io/flows/configuration-and-expressions/secrets

Example of referencing multiple secrets directly in app installation configuration fields.

```javascript
secrets.DEMO_BOT_SLACK_BOT_TOKEN
secrets.DEMO_BOT_SLACK_SIGNING_SECRET
```

--------------------------------

### Uninstall Spacelift example

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/install

Example of running the uninstall script with default options.

```bash
./uninstall.sh
```

--------------------------------

### Install Tempo Helm chart

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-otel-grafana-stack

Installs the Tempo Helm chart into the monitoring namespace using the provided values file.

```bash
helm install tempo grafana/tempo -n monitoring -f tempo-values.yaml
```

--------------------------------

### Check liftoff version

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Verifies the installation and prints the installed version. Use this to confirm you have the intended version, especially if you were directed to a release candidate.

```bash
liftoff --version
```

--------------------------------

### Start the browser UI with liftoff ui --beta

Source: https://docs.spacelift.io/product/migrating-to-spacelift/ui

Run this command to start the browser UI. The `--beta` flag is required because the UI is in beta; without it, the command refuses to run.

```bash
liftoff ui --beta
```

--------------------------------

### vpc_config JSON for custom VPC installation

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/advanced-installations

Example vpc_config section for a custom VPC installation. Set use_custom_vpc to true and provide VPC, subnet, security group, and availability zone IDs. After populating, run the installer as described in the installation guide.

```json
{
    "vpc_config": {
        "use_custom_vpc": true,
        "vpc_id": "vpc-091e6f4d35908e7c1",
        "private_subnet_ids": "subnet-01a25f47c5a7e94fc,subnet-035169be40fbfbbbf,subnet-09c72e8ab5499eed1",
        "public_subnet_ids": "subnet-08aa756ab626d690f,subnet-0d03bb49f32922d93,subnet-0d85c4a80db226099",
        "drain_security_group_id": "sg-045061f7120343acd",
        "load_balancer_security_group_id": "sg-086a38a75894c4fc5",
        "server_security_group_id": "sg-0cb943fd285fc5c85",
        "scheduler_security_group_id": "sg-0ef464fd834fc5a43",
        "installation_task_security_group_id": "sg-03b9b0e17cce91d3a",
        "database_security_group_id": "sg-0b67dd8ad00e237fd",
        "availability_zones": "eu-west-1a,eu-west-1b,eu-west-1c"
    }
}
```

--------------------------------

### Install a plugin with OpenTofu using spacelift_plugin and spacelift_plugin_template

Source: https://docs.spacelift.io/integrations/plugins

Creates a plugin instance from the 'opentofu-tracing' template with a stack label and parameters. The data source fetches the template ID, and the resource installs the plugin with the specified configuration.

```HCL
data "spacelift_plugin_template" "opentofu_tracing" {
  plugin_template_id = "opentofu-tracing"
}

resource "spacelift_plugin" "opentofu_tracing" {
  plugin_template_id = data.spacelift_plugin_template.opentofu_tracing.id
  name               = "OpenTofu Tracing Plugin"
  stack_label        = "tracing"
  parameters = {
    output_file = "tracing_output.md"
  }
}
```

--------------------------------

### Install stable liftoff with Homebrew

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Installs the current stable release of liftoff via Homebrew. This is the recommended method for most users. Running this will replace any previously installed release candidate without warning.

```bash
brew install spacelift-solutions/tap/liftoff
```

--------------------------------

### config.yaml repository_map example

Source: https://docs.spacelift.io/product/migrating-to-spacelift/audit

Example of setting `source.repository_map` in `config.yaml` to reference a `repos.yaml` file.

```yaml
source:
  repository_map: "@repos.yaml"
```

--------------------------------

### workflow.yml example for my-custom-tool

Source: https://docs.spacelift.io/self-hosted/latest/vendors/kubernetes/workflow-tool

Example configuration for a custom workflow tool named 'my-custom-tool'. It defines commands for createFromStdin, apiResources, apply, rolloutStatus, getPods, delete, and get. The configuration is stored in a workflow.yml file in the .spacelift folder.

```yaml
createFromStdin: "my-custom-tool create -f - -o yaml"
apiResources: "my-custom-tool api-resources {{ if .NoHeaders }}--no-headers {{ end }}--verbs=list,create {{ if .IsNamespaced }}--namespaced {{ end }}-o {{ .OutputFormat }}"
apply: "my-custom-tool apply -k ./ --prune {{ .PruneWhiteList }} -l \"spacelift-stack={{ .StackSlug }}\" --dry-run={{ .DryRunStrategy }}{{ if .OutputFormat }} -o {{ .OutputFormat }}{{ end }}{{ if .Namespace }} --namespace={{ .Namespace }}{{ end}}"
rolloutStatus: "my-custom-tool rollout status{{ if .Namespace }} --namespace={{ .Namespace }}{{ end}} --timeout {{ .RolloutTimeoutInSeconds }}s -w {{ .Id }}"
getPods: "my-custom-tool get pods{{ if .Namespace }} --namespace={{ .Namespace }}{{ else }} --all-namespaces{{ end}} -w -l '{{ .Pods }}'"
delete: "my-custom-tool delete --ignore-not-found -l spacelift-stack={{ .StackSlug }}{{ if .Namespace }} --namespace={{ .Namespace }}{{ else }} --all-namespaces{{ end}} {{ .ResourcesToDelete }}"
get: "my-custom-tool get -o json --show-kind --ignore-not-found -l spacelift-stack={{ .StackSlug }}{{ if .Namespace }} --namespace={{ .Namespace }}{{ else }} --all-namespaces{{ end}} {{ .ResourceKindsToGet }}"
```

--------------------------------

### Install liftoff to a custom directory with INSTALL_DIR

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Installs liftoff to a custom directory instead of /usr/local/bin. Useful when /usr/local/bin requires root access.

```bash
curl -fsSL https://raw.githubusercontent.com/spacelift-solutions/liftoff/main/install.sh | INSTALL_DIR="$HOME/.local/bin" sh
```

--------------------------------

### Install Datadog agent with custom tags

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-datadog

Installs the Datadog agent with additional custom tags for organizing telemetry data. Uses example API key and site.

```bash
helm install datadog-agent \
    --namespace datadog \
    --set datadog.apiKey=12356apikey789 \
    --set datadog.site=datadoghq.com \
    --set "datadog.tags[0]=app:spacelift" \
    --set "datadog.tags[1]=environment:production" \
    datadog/datadog
```

--------------------------------

### liftoff discover output example

Source: https://docs.spacelift.io/product/migrating-to-spacelift/discover

Example output from `liftoff discover` for a Terraform Cloud/Enterprise source. Shows Sensitive Values, Counts, Spacelift Counts, and the next command (`liftoff batch list`).

```text
Source  terraform

Sensitive Values
  Sensitive Variables  22
  Captured             0
  Empty                22

  Notes (2)
    - 19 sensitive stack variable value(s) are empty — stage the stacks, then run `liftoff mutate` with a capability
      that captures them (`liftoff sources` lists what this source declares), or set them in Spacelift after the
      migration
    - 3 sensitive context variable value(s) are empty — stage the contexts, then run `liftoff mutate` with a capability
      that captures them (`liftoff sources` lists what this source declares), or set them in Spacelift after the
      migration

Counts
  Context Variables  6
  Contexts           3
  Modules            1
  Mounted Files      0
  Spaces             9
  Stack Variables    41
  Stacks             13

Spacelift Counts
  Spaces            8
  VCS Integrations  4
  Worker Pools      1

Next
  $ liftoff batch list
```

--------------------------------

### Transform configuration YAML

Source: https://docs.spacelift.io/product/migrating-to-spacelift/transform

Example YAML configuration for the `liftoff transform` command. Settings are kept under the subcommand they control, with `transform.workflow-tool` and `transform.stack-labels` keys. Each additional transformation gets its own subcommand.

```yaml
transform:
  workflow-tool:
    target: OPEN_TOFU
    version: 1.8.7
  stack-labels:
    add: team:payments,env:prod
```

--------------------------------

### Install spacectl-bin from AUR

Source: https://docs.spacelift.io/concepts/spacectl

Installs spacectl-bin from the Arch User Repository using yay. Verify the PKGBUILD before installing.

```bash
yay -S spacectl-bin
```

--------------------------------

### Install spacectl from Alpine repository

Source: https://docs.spacelift.io/concepts/spacectl

Installs spacectl from the Alpine edge/testing repository using apk. Verify the APKBUILD before installing.

```bash
apk add spacectl --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing
```

--------------------------------

### Install a specific liftoff version with VERSION

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Installs an exact version of liftoff using the install script. The VERSION environment variable must be set on the sh command, not in front of curl, to take effect. This is recommended for reproducible CI builds.

```bash
curl -fsSL https://raw.githubusercontent.com/spacelift-solutions/liftoff/main/install.sh | VERSION=v1.3.0 sh
```

--------------------------------

### Examples of using outputs in expressions

Source: https://docs.spacelift.io/flows/configuration-and-expressions/input-output-event-data

Provides practical examples of using `outputs` in Slack messages, conditional logic, and dynamic URLs.

```javascript
// Slack message
`Hello <@${outputs.getUserName.name}>! Your role is: ${outputs.getUserRole.role}`

// Conditional logic
outputs.accessCheck.allowed && outputs.getUserRole.role === 'admin'

// Dynamic URL
`https://api.example.com/users/${outputs.getUserName.email}/permissions`
```

--------------------------------

### Install new controller version (kubectl)

Source: https://docs.spacelift.io/concepts/worker-pools/kubernetes-workers

After uninstalling the old controller, install the new v0.0.17 controller using kubectl apply.

```bash
kubectl apply -f https://downloads.spacelift.io/kube-workerpool-controller/v0.0.17/manifests.yaml
```

--------------------------------

### Install stable liftoff without Homebrew

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Installs the current stable release of liftoff using the official install script. This method is for systems without Homebrew.

```bash
curl -fsSL https://raw.githubusercontent.com/spacelift-solutions/liftoff/main/install.sh | sh
```

--------------------------------

### Install spacectl with winget

Source: https://docs.spacelift.io/concepts/spacectl

Installs spacectl on Windows using winget. Two equivalent commands are shown.

```bash
winget install spacectl
```

```bash
winget install --id spacelift-io.spacectl
```

--------------------------------

### Switch from release candidate to stable liftoff

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Uninstalls the release candidate and installs the stable version. Homebrew does not allow both to be installed simultaneously because they provide the same command.

```bash
brew uninstall liftoff-rc && brew install spacelift-solutions/tap/liftoff
```

--------------------------------

### Install or upgrade Jaeger with Badger storage

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-otel-jaeger

Commands to install Jaeger for the first time or upgrade an existing installation using the 'jaeger-values.yaml' file.

```bash
# If installing for the first time:
helm install jaeger jaegertracing/jaeger -n monitoring -f jaeger-values.yaml

# If upgrading an existing installation:
helm upgrade jaeger jaegertracing/jaeger -n monitoring -f jaeger-values.yaml
```

--------------------------------

### Install VCS agent Helm chart with environment variables

Source: https://docs.spacelift.io/concepts/vcs-agent-pools

Installs the VCS agent Helm chart, passing the pool token, endpoint, and vendor from environment variables. Assumes those variables are already set.

```bash
helm upgrade vcs-agent spacelift/vcs-agent --install --set "credentials.token=$SPACELIFT_VCS_AGENT_POOL_TOKEN,credentials.endpoint=$SPACELIFT_VCS_AGENT_TARGET_BASE_ENDPOINT,credentials.vendor=$SPACELIFT_VCS_AGENT_VENDOR"
```

--------------------------------

### Comprehensive Blueprint YAML Example

Source: https://docs.spacelift.io/self-hosted/latest/concepts/blueprint

A comprehensive Spacelift blueprint YAML example covering all available configuration options, including inputs with various types, options, stack settings, and attachments. Demonstrates usage of context, roles, and cloud attachments.

```yaml
inputs:
  - id: environment
    name: Environment to deploy to
    # type is not mandatory, defaults to short_text
  - id: app
    name: App name (used for naming convention)
    type: short_text
  - id: description
    name: Description of the stack
    type: long_text
    # long_text means you'll have a bigger text area in the UI
  - id: connstring
    name: Connection string to the database
    type: secret
    # secret means the input will be masked in the UI
  - id: tf_version
    name: OpenTofu/Terraform version of the stack
    type: select
    options:
      - "1.3.0"
      - "1.4.6"
      - "1.5.0"
  - id: manage_state
    name: Should Spacelift manage the state of OpenTofu/Terraform
    default: true
    type: boolean
  - id: destroy_task_epoch
    name: Epoch timestamp of when to destroy the resources
    type: number
options:
  # If true, a tracked run will be triggered right after the stack is created
  trigger_run: true
  # If true, the stack will not be created, useful when using inputs and multiple stacks in a single template.
  do_not_create: false
stack:
  name: ${{ inputs.app }}-{{ inputs.environment }}-stack
  space: root
  # The single-quote is needed to avoid YAML parsing errors since the question mark
  # and the colon are reserved characters in YAML.
  description: '${{ inputs.environment == "prod" ? "Production stack" : "Non-production stack" }} Stack created at ${{ string(context.time) }}.'
  is_disabled: ${{ inputs.environment != 'prod' }}
  labels:
    - Environment/${{ inputs.environment }}
    - Vendor/Terraform
    - Owner/${{ context.user.login }}
    - Blueprint/${{ context.blueprint.name }}
    - Space/${{ context.blueprint.space }}
  administrative: false # Deprecated in favor of attachments.roles. Do not use this field because it'll be ineffective in the future.
  allow_promotion: false
  auto_deploy: false
  auto_retry: false
  local_preview_enabled: true
  secret_masking_enabled: true
  protect_from_deletion: false
  runner_image: public.ecr.aws/mycorp/spacelift-runner:latest
  worker_pool: 01GQ29K8SYXKZVHPZ4HG00BK2E
  attachments:
    contexts:
      - id: my-first-context-vnfq2
        priority: 1
    roles:
      - role_id: "01GQ29K8SYXKZVHPZ4HG00BK2E"
        space_id: "devops-01K71X37VCMF9D6W1SZRG8EGBE"
    clouds:
      aws:
        id: 01GQ29K8SYXKZVHPZ4HG00BK2E
        read: true
        write: true
      azure:

```

--------------------------------

### Install spacectl with asdf

Source: https://docs.spacelift.io/concepts/spacectl

Installs spacectl using the asdf version manager.

```bash
asdf plugin add spacectl
asdf install spacectl latest
asdf global spacectl latest
```

--------------------------------

### Output of liftoff init

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Example output after running `liftoff init`. It shows the configuration directory, config path, and database path, followed by suggested next commands.

```text
Config Created  yes
Config Dir      /tmp/migration-demo/.liftoff
Config Path     /tmp/migration-demo/.liftoff/config.yaml
Db Path         /tmp/migration-demo/.liftoff/liftoff.db

Next
  $ liftoff sources
  $ liftoff configure --source <id> --set source.<key>=value
```

--------------------------------

### Install Datadog agent with Helm

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-datadog

Installs the Datadog agent using Helm. Replace <DATADOG_API_KEY> and <DATADOG_SITE> with your actual values.

```bash
helm install datadog-agent \
    --namespace datadog \
    --set datadog.apiKey=<DATADOG_API_KEY> \
    --set datadog.site=<DATADOG_SITE> \
    datadog/datadog
```

--------------------------------

### Get Spacelift ingress address with kubectl

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/deploying-to-eks

Retrieves the ingress details for the Spacelift application. The `ADDRESS` field provides the load balancer domain name needed for DNS setup. The example output shows a typical ingress named `server-v4`.

```bash
$ kubectl get ingresses --namespace "$K8S_NAMESPACE"
NAME        CLASS   HOSTS                     ADDRESS                                                                    PORTS     AGE
server-v4   alb     spacelift.example.com     k8s-spacelif-serverv4-1234567890-1234567890.eu-west-1.elb.amazonaws.com    80, 443   5m32s
```

--------------------------------

### Install Grafana chart with Helm

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-otel-grafana-stack

Installs the Grafana Helm chart into the monitoring namespace using the provided values file.

```bash
helm install grafana grafana/grafana -n monitoring -f grafana-values.yaml
```

--------------------------------

### Blueprint vcs configuration example

Source: https://docs.spacelift.io/self-hosted/latest/concepts/blueprint

YAML example of the mandatory `vcs` section. Shows optional `id`, `branch`, `project_root`, `project_globs`, `namespace`, `repository`, `repository_url`, and `provider` fields. `repository_url` is only needed for `RAW_GIT`; `id` is optional for non-default integrations.

```yaml
  vcs:
    id: "github-for-my-org" # Optional, only needed if you want to use a non-default VCS integration. Use the "Copy ID" button to get the ID.
    branch: main
    project_root: modules/networking
    project_globs: # Project globs do not mount the files or directories in your project root. They are used primarily for triggering your stack when for example there are changes to a module outside of the project root.
      - "terraform/**"
      - "k8s/**"
    namespace: "my-namespace" # The VCS organization name or project namespace.
    repository: my-repository # Name of the repository.
    repository_url: "https://www.github.com/my-namespace/my-repository" # This is only needed for RAW_GIT
    provider: GITHUB_ENTERPRISE # Possible values: AZURE_DEVOPS, BITBUCKET_CLOUD, BITBUCKET_DATACENTER, GITHUB, GITHUB_ENTERPRISE, GITLAB, RAW_GIT

```

--------------------------------

### Install OpenTelemetry Collector with Helm

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-otel-jaeger

Installs the OpenTelemetry Collector into the monitoring namespace using the values file otel-collector-values.yaml.

```bash
helm install otelcol open-telemetry/opentelemetry-collector --namespace monitoring -f otel-collector-values.yaml
```

--------------------------------

### Initialize the workspace with liftoff init

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Run `liftoff init` in the directory where you want the workspace. It creates `./.liftoff/` with an empty `config.yaml` and the SQLite store. Running it again on an existing workspace reports `Config Created no` and changes nothing.

```bash
liftoff init
```

--------------------------------

### Get MQTT broker service address with kubectl

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/deploying-to-eks

Retrieves the service details for the MQTT broker when using external workers. The `EXTERNAL-IP` field provides the load balancer domain name needed for DNS setup. The example output shows a typical service named `spacelift-mqtt`.

```bash
$ kubectl get services --namespace "$K8S_NAMESPACE" "spacelift-mqtt"
NAME             TYPE           CLUSTER-IP      EXTERNAL-IP                                                               PORT(S)          AGE
spacelift-mqtt   LoadBalancer   172.20.252.37   k8s-spacelif-spacelif-1234567890-1234567890.elb.eu-north-1.amazonaws.com  1984:30498/TCP   5m49s
```

--------------------------------

### repos.yaml mapping example

Source: https://docs.spacelift.io/product/migrating-to-spacelift/audit

Example `repos.yaml` file that maps source repository patterns to target repositories. It includes a wildcard pattern for `dev-*` and a specific mapping for `ws-special`.

```yaml
# repos.yaml
"space:Core Infra": acme/core-infra
"dev-*":
  namespace: acme
  repository: dev-repo
  branch: main
  provider: GITHUB
ws-special: acme/special-repo
```

--------------------------------

### Example of referencing an S3 bucket ARN signal

Source: https://docs.spacelift.io/flows/configuration-and-expressions/input-output-event-data

Example of referencing a signal from an S3 Bucket Resource to get its ARN.

```javascript
signals.myS3Bucket.arn  // AWS S3 bucket ARN reference
```

--------------------------------

### Example requirements.yml file

Source: https://docs.spacelift.io/self-hosted/latest/vendors/ansible/ansible-galaxy

An example requirements.yml file that defines a collection dependency (community.grafana version 1.3.1) to be installed by Ansible Galaxy.

```yaml
---
collections:
  - name: community.grafana
    version: 1.3.1

```

--------------------------------

### liftoff sources command

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Lists every source this binary can migrate from, with the settings each one takes. Read-only; run it as often as you like.

```bash
liftoff sources
```

--------------------------------

### Install Backstage plugins with yarn

Source: https://docs.spacelift.io/integrations/external-integrations/backstage

Run these commands from the root of your Backstage project to install the Spacelift backend and frontend plugins. Requires Backstage v1.17.0 or above.

```bash
yarn --cwd packages/backend add @spacelift-io/backstage-integration-backend
yarn --cwd packages/app add @spacelift-io/backstage-integration-frontend
```

--------------------------------

### Initialize OpenTofu working directory

Source: https://docs.spacelift.io/flows/self-hosting/deploy-to-eks

Runs 'tofu init' to initialize the working directory and download required providers for the Spacelift Flows deployment.

```bash
tofu init

```

--------------------------------

### Full DR config file example

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/disaster-recovery

Example config file for a DR region. Set aws_region to the secondary region, disable_services to true, and provide database connection string SSM ARNs, load balancer certificate ARN, and the disaster_recovery section. The hostname and iot_broker_endpoint should be set appropriately.

```json
{
    "account_name": "test-org",
    "aws_region": "eu-west-3",
    "disable_services": true,
    "database": {
        "connection_string_ssm_arn": "arn:aws:secretsmanager:eu-west-3:012345678901:secret:spacelift/database-secondary-BAD0vA",
        "connection_string_ssm_kms_arn": "arn:aws:kms:eu-west-3:012345678901:key/1a5a0be1-b083-43dc-babf-384766b4446e"
    },
    "load_balancer": {
        "certificate_arn": "arn:aws:acm:eu-west-3:012345678901:certificate/e2f6cfce-4925-4e85-8dcd-dbb2871583cd",
        "ssl_policy": "ELBSecurityPolicy-TLS-1-2-2017-01",
        "scheme": "internet-facing"
    },
    "disaster_recovery": {
        "is_dr_instance": true,
        "replica_region": "eu-west-1",
        "encryption_primary_key_arn": "arn:aws:kms:eu-west-1:012345678901:key/mrk-abc92048ad9283944ab23cc22342b43f",
        "s3_bucket_replication": {
          "enabled": true,
          "replica_kms_key_arn": "arn:aws:kms:eu-west-1:012345678901:key/77218af9-085a-42d7-95b4-3a79be1fb08f",
          "states_bucket_arn": "arn:aws:s3:::012345678901-spacelift-states-ca9bf8",
          "run_logs_bucket_arn": "arn:aws:s3:::012345678901-spacelift-run-logs-ca9bf8",
          "run_observability_bucket_arn": "arn:aws:s3:::012345678901-spacelift-run-observability-ca9bf8",
          "modules_bucket_arn": "arn:aws:s3:::012345678901-spacelift-modules-ca9bf8",
          "policy_inputs_bucket_arn": "arn:aws:s3:::012345678901-spacelift-policy-inputs-ca9bf8",
          "workspaces_bucket_arn": "arn:aws:s3:::012345678901-spacelift-workspaces-ca9bf8"
        }
    },
    "hostname": "spacelift.myorg.com",
    "iot_broker_endpoint": "worker-iot.spacelift.myorg.com",
    ... other settings
}
```

--------------------------------

### Create initial version

Source: https://docs.spacelift.io/flows/developers/deploying-apps/custom-apps

Creates a draft version of the app. The -e flag is required; other options are optional.

```bash
flowctl version create -e main.ts
```

--------------------------------

### Apply OpenTofu configuration

Source: https://docs.spacelift.io/flows/self-hosting/deploy-to-eks

Runs 'tofu apply' to apply the configuration and create the infrastructure. When prompted, type 'yes' to confirm the deployment.

```bash
tofu apply

```

--------------------------------

### Example comment to trigger tracked run

Source: https://docs.spacelift.io/concepts/run/pull-request-comments

An example pull request comment that would trigger the tracked run policy. The comment must start with '/spacelift' and include the stack ID.

```text
/spacelift deploy my-stack-id

```

--------------------------------

### Install and use spacectl in GitHub Actions

Source: https://docs.spacelift.io/concepts/spacectl

GitHub Actions workflow using setup-spacectl to install spacectl and deploy a stack. Requires SPACELIFT_API_KEY_ENDPOINT, SPACELIFT_API_KEY_ID, and SPACELIFT_API_KEY_SECRET secrets.

```yaml
steps:
- name: Install spacectl
   uses: spacelift-io/setup-spacectl@main

- name: Deploy infrastructure
   env:
      SPACELIFT_API_KEY_ENDPOINT: https://mycorp.app.spacelift.io
      SPACELIFT_API_KEY_ID: ${{ secrets.SPACELIFT_API_KEY_ID }}
      SPACELIFT_API_KEY_SECRET: ${{ secrets.SPACELIFT_API_KEY_SECRET }}
   run: spacectl stack deploy --id my-infra-stack
```

--------------------------------

### Complete Terraform source config.yaml example

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

A complete Terraform source example for writing .liftoff/config.yaml by hand. Environment references stay exactly as written on disk; the command that uses a value resolves it from the environment, so export each referenced variable before validating or running the migration. After any hand edit, run liftoff configure validate.

```yaml
exporter: terraform
source:
  api_endpoint: https://app.terraform.io
  api_token: ${TFC_TOKEN}

spacelift:
  endpoint: https://example.app.spacelift.io
  api_key_id: ${SPACELIFT_KEY_ID}
  api_key_secret: ${SPACELIFT_KEY_SECRET}
  repo_name: liftoff
  admin_stack_name: liftoff-admin
  space: root

vcs:
  token: ${VCS_TOKEN}

transform:
  workflow-tool:
    target: OPEN_TOFU
    version: 1.8.7
  stack-labels:
    add: team:payments,env:prod
```

--------------------------------

### Run liftoff discover

Source: https://docs.spacelift.io/product/migrating-to-spacelift/discover

Pulls everything from the source into the local store. Read-only, idempotent, and resumable; progress goes to stderr. Add -v for more detail, -vv for even more.

```bash
liftoff discover
```

--------------------------------

### Create a new app

Source: https://docs.spacelift.io/flows/developers/deploying-apps/custom-apps

Prompts for app name, description, block color, icon URL, and optional project ID. Returns an app ID for version management.

```bash
flowctl app create
```

--------------------------------

### liftoff publish --confirm --proof-token

Source: https://docs.spacelift.io/product/migrating-to-spacelift/publish

Applies the plan using the proof token from the previous publish. Requires explicit --confirm and a valid token.

```bash
liftoff publish --confirm --proof-token <token from the plan>
```

--------------------------------

### disaster_recovery configuration section

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/disaster-recovery

Example of the disaster_recovery section in the config file. Set is_dr_instance to true, replica_region to the primary region, and provide the encryption_primary_key_arn from the primary installation. Ensure s3_bucket_replication.enabled is true and populate the bucket ARNs from the installer output.

```json
"disaster_recovery": {
  "is_dr_instance": true,
  "replica_region": "eu-west-1",
  "encryption_primary_key_arn": "arn:aws:kms:eu-west-1:012345678901:key/mrk-abc92048ad9283944ab23cc22342b43f",
  "s3_bucket_replication": {
    "enabled": true,
    "replica_kms_key_arn": "arn:aws:kms:eu-west-1:012345678901:key/77218af9-085a-42d7-95b4-3a79be1fb08f",
    "states_bucket_arn": "arn:aws:s3:::012345678901-spacelift-states-ca9bf8",
    "run_logs_bucket_arn": "arn:aws:s3:::012345678901-spacelift-run-logs-ca9bf8",
    "run_observability_bucket_arn": "arn:aws:s3:::012345678901-spacelift-run-observability-ca9bf8",
    "modules_bucket_arn": "arn:aws:s3:::012345678901-spacelift-modules-ca9bf8",
    "policy_inputs_bucket_arn": "arn:aws:s3:::012345678901-spacelift-policy-inputs-ca9bf8",
    "workspaces_bucket_arn": "arn:aws:s3:::012345678901-spacelift-workspaces-ca9bf8"
  }
},
```

--------------------------------

### Install Spacelift Flows Helm Chart

Source: https://docs.spacelift.io/flows/self-hosting/deploy-to-eks

Adds the Spacelift Helm repository, updates it, and installs the spacelift-flows chart using the flows-values.yaml file in the specified namespace.

```bash
helm repo add spacelift https://downloads.spacelift.io/helm
helm repo update

helm upgrade spacelift-flows spacelift/spacelift-flows --install -f flows-values.yaml --namespace $TF_VAR_k8s_namespace
```

--------------------------------

### VCS Configuration Example

Source: https://docs.spacelift.io/concepts/blueprint

Example of a VCS section in a Spacelift blueprint. The vcs section is mandatory and requires branch, repository, and provider. For non-GITHUB and non-RAW_GIT providers, namespace is required. For RAW_GIT, provide repository_url instead of namespace and repository, and do not include an id. The id is optional for non-default integrations.

```yaml
  vcs:
    id: "github-for-my-org" # Optional, only needed if you want to use a non-default VCS integration. Use the "Copy ID" button to get the ID.
    branch: main
    project_root: modules/networking
    project_globs: # Project globs do not mount the files or directories in your project root. They are used primarily for triggering your stack when for example there are changes to a module outside of the project root.
      - "terraform/**"
      - "k8s/**"
    namespace: "my-namespace" # The VCS organization name or project namespace.
    repository: my-repository # Name of the repository.
    repository_url: "https://www.github.com/my-namespace/my-repository" # This is only needed for RAW_GIT
    provider: GITHUB_ENTERPRISE # Possible values: AZURE_DEVOPS, BITBUCKET_CLOUD, BITBUCKET_DATACENTER, GITHUB, GITHUB_ENTERPRISE, GITLAB, RAW_GIT
```

--------------------------------

### Example validation output for Terraform Cloud/Enterprise

Source: https://docs.spacelift.io/product/migrating-to-spacelift/setup

Example output from `liftoff configure validate` for a Terraform Cloud/Enterprise configuration. It validates the Terraform source shown in step 2.

```text
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
```

--------------------------------

### Initial Slack Configuration in config.json

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/cloudformation/slack-integration-setup

Populate the slack_config section of the config.json file with the client ID, client secret, and signing secret from your Slack app's Basic Information tab. Enable the integration by setting enabled to true. After populating, run the installer as described in the installation guide.

```json
{
    "slack_config": {
        "enabled": true,
        "client_id": "<client id here>",
        "client_secret": "<client secret here>",
        "signing_secret": "<signing secret here>"
    }
}
```

--------------------------------

### Source shell environment variables

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/deploying-to-aks

Sources the shell output from Terraform to export all required environment variables for the installation process. Keep the same shell open for the entire guide.

```bash
# Source in your shell all the required env vars to continue the installation process
$(tofu output -raw shell)
```

--------------------------------

### Rendered output of the blueprint example

Source: https://docs.spacelift.io/concepts/blueprint

The resulting stack definition after evaluating the template expressions in the example above. Shows concrete values for the random string, user login, blueprint name, UUID, and computed timestamp.

```yaml
stack:
  name: integration-tests-my-app-vG3j3a
  description: |
    Temporary integration test stack for my-app. Deployed in 2023.
    The base blueprint was created at 2020-01-01T10:00:20.021-05:00.
  labels:
    - owner/johndoe
    - blueprints/my-blueprint
  environment:
    variables:
      - name: DEPLOYMENT_ID
        value: 6c9c4e3e-6b5d-4b3a-9c9c-4e3e6b5d4b3a
  schedules:
    delete:
      delete_resources: true # Russian roulette
      timestamp_unix: 1674139424 # Delete the stack in 30 minutes
```

--------------------------------

### Create Working Directory

Source: https://docs.spacelift.io/flows/self-hosting/deploy-to-eks

Creates a new directory for the infrastructure deployment and navigates into it.

```bash
mkdir spacelift-flows-infra
cd spacelift-flows-infra
```

--------------------------------

### spacectl stack list - example output

Source: https://docs.spacelift.io/concepts/spacectl

Example output of `spacectl stack list` showing two stacks with their commit, author, state, worker pool, and locked by information.

```text
> spacectl stack list
Name                          | Commit   | Author        | State     | Worker Pool | Locked By
stack-1                       | 1aa0ef62 | Adam Connelly | NONE      |             |
stack-2                       | 1aa0ef62 | Adam Connelly | DISCARDED |             |
```

--------------------------------

### Filter users by userName

Source: https://docs.spacelift.io/integrations/single-sign-on/scim

Example of filtering users by the userName attribute using the eq operator. The endpoint is GET /scim/v2/Users?filter=userName eq "john@example.com".

```http
GET /scim/v2/Users?filter=userName eq "john@example.com"
```

--------------------------------

### Install Jaeger Helm chart

Source: https://docs.spacelift.io/self-hosted/latest/installing-spacelift/reference-architecture/guides/telemetry/k8s-otel-jaeger

Installs the Jaeger chart into the monitoring namespace using the provided values file. Uses in-memory storage, which is ephemeral and suitable for development, testing, and demo environments.

```bash
helm install jaeger jaegertracing/jaeger -n monitoring -f jaeger-values.yaml
```

--------------------------------

### OIDC Policy with Wildcards

Source: https://docs.spacelift.io/integrations/cloud-providers/oidc

Example policy condition using wildcards to match the subject claim format. The wildcards cover any internal space ID starting with 'production-', any stack, any run type, and any scope.

```json
"Condition": {
  "StringLike": {
    "yourSpaceliftDomain:sub": "space:production-*:stack:*:run_type:*:scope:*"
  }
}
```

--------------------------------

### Runtime configuration for spacectl (omit top-level config)

Source: https://docs.spacelift.io/concepts/configuration/runtime-configuration

When configuring an individual stack with spacectl (e.g., `stack deploy --id example --runtime-config ./config.yml`), omit the top-level config and start at `runner_image`.

```yaml
runner_image: your/first:runner
# And so on, following the full
# configuration schema example.
```

--------------------------------

### workflow.yml example for custom tool 'super-iac'

Source: https://docs.spacelift.io/self-hosted/latest/vendors/opentofu/workflow-tool

Example configuration for a custom workflow tool named 'super-iac'. The file must be stored at {reporoot}/.spacelift/workflow.yml and only the .yml extension is read. It defines commands for init, workspace selection, plan, show, output, apply, and destroy.

```yaml
init: super-iac init -input=false
workspaceSelect: super-iac workspace select "{{ .WorkspaceName }}"
workspaceNew: super-iac workspace new "{{ .WorkspaceName }}"
plan: super-iac plan -input=false -lock={{ .Lock }} {{ if not .Refresh }}-refresh=false {{ end }}-out={{ .PlanFileName }} {{ range .Targets }}-target='{{ . }}' {{ end }}
showState: super-iac show -json
showPlan: super-iac show -json "{{ .PlanFileName }}"
getOutputs: super-iac output -json
apply: super-iac apply -auto-approve -input=false "{{ .PlanFileName }}"
destroy: super-iac destroy -auto-approve -input=false
```

--------------------------------

### Deploy a module with version and inputs

Source: https://docs.spacelift.io/concepts/intelligence/intent/spacelift-modules

Specify a version and provide input values in the same request. Intent validates that the version exists and is active, and that all required inputs are supplied.

```text
Deploy the elb module at version 1.2.0, with the web load balancer inputs.
```

--------------------------------

### Blueprint YAML using context properties

Source: https://docs.spacelift.io/concepts/blueprint

Example blueprint stack definition that uses `context.random_string`, `context.time`, `context.blueprint.created_at`, `context.user.login`, `context.blueprint.name`, `context.random_uuid`, and `context.random_number`. Note that this is not a working example as it is missing required sections like `inputs` and `vcs`.

```yaml
stack:
  name: integration-tests-${{ inputs.app }}-${{ context.random_string }}
  description: |
    Temporary integration test stack for ${{ inputs.app }}. Deployed in ${{ context.time.getFullYear() }}.
    The base blueprint was created at ${{ string(context.blueprint.created_at) }}.
  labels:
    - owner/${{ context.user.login }}
    - blueprints/${{ context.blueprint.name }}
  environment:
    variables:
      - name: DEPLOYMENT_ID
        value: "${{ context.random_uuid }}"
  schedules:
    delete:
      delete_resources: ${{ context.random_number % 2 == 0 }} # Russian roulette
      timestamp_unix: ${{ int(context.time) + duration("30m").getSeconds() }} # Delete the stack in 30 minutes
```

--------------------------------

### Pin Spacelift provider version with required_providers

Source: https://docs.spacelift.io/self-hosted/latest/vendors/terraform/terraform-provider

Use this Terraform configuration to pin the Spacelift provider to a known-compatible version for self-hosted installations. The example sets version to 1.14.0, but you should choose the version that matches your self-hosted version from the compatibility table.

```hcl
terraform {
    required_providers {
        spacelift = {
            source = "spacelift-io/spacelift"
            version = "1.14.0"
        }
    }
}
```

--------------------------------

### Apply OpenTofu Infrastructure Changes

Source: https://docs.spacelift.io/flows/self-hosting/deploy-to-eks

Run these commands to plan and apply OpenTofu configuration changes for the infrastructure. The plan command shows the changes, and apply executes them.

```bash
tofu plan
```

```bash
tofu apply
```

--------------------------------

### Verify flowctl installation

Source: https://docs.spacelift.io/flows/developers/deploying-apps/custom-apps

Checks the installed flowctl version to confirm the installation succeeded.

```bash
flowctl --version
```
Tokens:
Raw