Command Reference

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:

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

Options

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

Option	Short	Default	Description
`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`	`-h`		The hostname or group of hosts to configure server access on.
`--port`	`-p`	`22`	The port to SSH into the server with.
`--user`	`-u`	The username of your HOST machine (run `whoami` in a new terminal)	The user to SSH into the server with.
`--upgrade`	`-U`	Check 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.

Variable	Description	Example Value	Required
`<ENVIRONMENT>_ENV_FILE_BASE64`	The base64 encoded `.env` file.	`ABCDEFG1234...`	⚠️ Yes
`<ENVIRONMENT>_SSH_REMOTE_HOSTNAME`	The hostname/IP of your server.	`server01.example.com`	⚠️ Yes
`SSH_DEPLOY_PRIVATE_KEY`	The private SSH key dedicated for the deploy user.	`-----BEGIN OPENSSH PRIVATE KEY-----abc123...`	⚠️ Yes
`SSH_REMOTE_KNOWN_HOSTS`	If 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_KEYS`	Makes 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:

Go to your GitHub repository.
Click on Settings.
Click on Secrets and variables → 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

Command reference for "spin build"

debug

Command reference for "spin debug"