Spin Pro Logo

configure

Command reference for "spin configure"

Configure various aspects of your project's deployment settings and infrastructure.

Usage

Usage for "spin configure"
spin configure <command> [options]

Commands

GitHub Actions (gha)

Configure GitHub Actions settings for deploying your application to a specific environment.

Configure GitHub Actions for an environment
spin configure gha [--env] <environment>

What this command does

When configuring GitHub Actions, this command:

  1. Validates your project setup and GitHub repository connection
  2. Creates or uses an existing deployment SSH key
  3. Base64 encodes your environment file
  4. Sets up required GitHub Actions secrets
  5. Configures server access for deployments

Options

The following options are available to set when running this command.

OptionShortDefaultDescription
environment-Required. The target environment to configure (e.g., production, staging).
--env-Only update the <ENVIRONMENT>_ENV_FILE_BASE64 secret. Skips steps 2 and 5 above, so it never connects to your servers.
--host-hThe hostname or group of hosts to configure server access on.
--port-p22The port to SSH into the server with.
--user-uThe username of your HOST machine (run whoami in a new terminal)The user to SSH into the server with.
--upgrade-UCheck for Ansible collection updates once per day.Force upgrade the Ansible Collection on your machine before configuring.

Example

Configure GitHub Actions for production
spin configure gha production
Update only the production environment file
spin configure gha production --env

Prerequisites

Before running spin configure gha, ensure you:

  • Have a GitHub repository set up (git init and connected to GitHub)
  • Are authenticated with GitHub CLI (spin gh auth login)
  • Have an environment file (e.g., .env.production for production)
  • Have your server provisioned with spin provision

With --env, only the first three apply. It doesn't read your .spin.yml, doesn't need an .infrastructure folder, and never connects to a server.

Environment Files

The command expects an environment file matching your target environment:

  • Production: .env.production
  • Staging: .env.staging
  • etc.

GitHub Actions Secrets

The following environment variables are set as secrets in GitHub Actions.

VariableDescriptionExample ValueRequired
<ENVIRONMENT>_ENV_FILE_BASE64The base64 encoded .env file.ABCDEFG1234...⚠️ Yes
<ENVIRONMENT>_SSH_REMOTE_HOSTNAMEThe hostname/IP of your server.server01.example.com⚠️ Yes
SSH_DEPLOY_PRIVATE_KEYThe private SSH key dedicated for the deploy user.-----BEGIN OPENSSH PRIVATE KEY-----abc123...⚠️ Yes
SSH_REMOTE_KNOWN_HOSTSIf provided, the SSH connection will validate the connection against your known_hosts file and remove the "SSH_KNOWN_HOST" warning. (Learn more)github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...no
AUTHORIZED_KEYSMakes an authorized_keys file containing the public keys of "sudo" users that can be used for authenticating other services via SSH (like database GUI connections).ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...no

To view these environment variables in GitHub Actions, you can follow these steps:

  1. Go to your GitHub repository.
  2. Click on Settings.
  3. Click on Secrets and variables → Actions.`

Adding a new secret to GitHub Actions

The only way you can update a value of a secret is to overwrite the previous value. GitHub Actions does not allow you to view the value of a secret once it's set. If you need to update a value, just run spin configure gha <environment> again.If your environment file is the only thing that changed, run spin configure gha <environment> --env instead. It updates <ENVIRONMENT>_ENV_FILE_BASE64 and leaves the other secrets untouched. This only needs GitHub authentication, so it works even without SSH access to your servers.

Special Notes

  • The command will create a new deployment key (under .infrastructure/conf/ci) if one doesn't exist
  • The command will connect to your server and set the newly created deployment key as an authorized key for the docker/deploy user on your server
  • All secrets are securely stored in your GitHub repository
  • The command validates your setup before making any changes

build

Trigger a build of your docker-compose files.

debug

If you run into an issue with `spin` and need to report a bug, this is a very helpful command that is used to tell the development team a little more about your environment and how you have `spin` configured.