Plugin Signed Runs

This module will create a Spacelift plugin that signs runs for Spacelift inside GitHub.

How it works

The module will create the following resource:

• A push policy inside spacelift
• An output you can use with a worker pool to pass the appropriate initialization policy to the workers.
  • This initialization policy is written as to not prevent stacks that are not signed from running (stacks not defined in var.stacks can still use this workerpool with no issues).
• For Every stack defined in var.stacks:
  • We will query for the repository defined in the specified stack_id, and we will commit a new workflow to that repository that will trigger a run in Spacelift with SpaceCTL.
    • The workflow will automatically configure the path in the workflow to only trigger based on the project root of the stack.
      • You can change this path with custom_path in the stacks variable.
    • You can also use a custom workflow by setting use_custom_workflow to true in the stacks variable.

1. A user pushes a code change to GitHub.
2. Spacelift is notified but ignores the code change push because of the Push policy.
3. The GitHub Action is triggered. It builds a JWT token and signs it with your secret. Then, it triggers a run and passes the signed token as metadata.
4. Spacelift schedules the run onto the private worker pool configured for the stack.
5. The private worker pool launcher evaluates the Initialization policy to verify the signature, that the token has not expired and is associated with the stack and commit for the run.
6. If the token validation succeeds, the launcher starts the worker, and the run gets executed. Otherwise, the worker does not get started, the run is marked as failed, and the reason for the failure is displayed in the Initialization phase logs.

Stacks Variable

This variable in the module will control which stacks will be allowed to run signed runs. The key can be anything, its only used statically in for_each loops.

• stack_id: The stack you want to trigger with signed runs.
• custom_path: Optional. If you want to trigger the stack using a path other than the stacks project root you can set it here.
• use_custom_workflow: Optional. If set to true, the module will not create a workflow in github for this stack. You will need to create a custom workflow in the repository.

Example

terraform {
  required_providers {
    spacelift = {
      source  = "spacelift-io/spacelift"
      version = ">=1.18.0"
    }

    github = {
      source  = "integrations/github"
      version = "~> 6.0"
    }
  }
}

provider "github" {
  token = "{your_github_token}" # WARNING Sensitive
}

module "plugin_signed_runs" {
  source = "spacelift.io/spacelift-solutions/plugin-signed-runs/spacelift"

  spacelift_api_endpoint         = "https://{your_account}.app.spacelift.io"
  spacelift_api_key_id           = "{your_spacelift_api_key_id}"
  spacelift_api_key_secret       = "{your_spacelift_api_key_secret}"                # WARNING Sensitive
  spacelift_run_signature_secret = "my-super-awesome-secret-that-no-one-will-guess" # WARNING Sensitive

  stacks = {
    my-great-stack = {
      stack_id    = "my-awesome-stack-id"
      custom_path = "my-great-stack/test"
    }

    my-second-great-stack = {
      stack_id            = "my-awesome-second-stack-id"
      use_custom_workflow = true
    }

    my-third-great-stack = {
      stack_id = "my-awesome-third-stack-id"
    }
  }
}

module "workerpool" {
  source = "github.com/spacelift-io/terraform-aws-spacelift-workerpool-on-ec2?ref=v2.6.2"

  configuration = <<-EOT
    export SPACELIFT_TOKEN="{your_workerpool_config_token}"
    export SPACELIFT_POOL_PRIVATE_KEY="{your_workerpool_private_key}"

    # This line is needed in order to pass the initialization policy to the workers
    ${module.plugin_signed_runs.initialization_policy}
  EOT
}

Inputs

Name	Description	Type	Default	Required
name	Name of the context	string	"plugin_signed_runs"	no
space	ID of the space the policy will be created in	string	"root"	no
spacelift_api_endpoint	The URL for your Spacelift account (e.g., https://acme.app.spacelift.io/)	string	n/a	yes
spacelift_api_key_id	Spacelift API key ID with admin permissions	string	n/a	yes
spacelift_api_key_secret	Spacelift API key secret with admin permissions	string	n/a	yes
spacelift_run_signature_secret	The secret that will be used to sign the JWT token. It can be any string.	string	n/a	yes
stacks	The stacks that will be triggered and signed via this plugin.	map(object({ stack_id = string custom_path = optional(string) use_custom_workflow = optional(bool) }))	n/a	yes

Outputs

Name	Description
initialization_policy	The initialization policy that must be assigned to the workerpool for this plugin to work.

Providers

Name	Version
github	~> 6.0
spacelift	>= 0.0.1

Resources

Name	Type
github_actions_secret.api_endpoint	resource
github_actions_secret.api_key_id	resource
github_actions_secret.api_key_secret	resource
github_actions_secret.run_signature_secret	resource
github_actions_secret.stack_ids	resource
github_repository_file.workflow	resource
spacelift_policy.this	resource
spacelift_policy_attachment.this	resource
spacelift_stack.this	data source