setup-trellis-cli
The roots/setup-trellis-cli action is a JavaScript action that sets up Trellis CLI in your GitHub Actions workflow by:
- Downloading a specific version of trellis-cli (defaults the latest) and adding it to the
PATH.
- Creating a
.vault_pass file with your Ansible Vault password input.
- Initializing the Trellis project in the GitHub repo by running the
trellis init command.
- Creates a virtual environment and installs dependencies (mainly Ansible) with automatic caching.
- Installs Ansible galaxy roles by running
trellis galaxy install with automatic caching.
See the Deploying Trellis WordPress Sites with GitHub Actions guide.
Support us
Roots is an independent open source org, supported only by developers like you. Your sponsorship funds WP Packages and the entire Roots ecosystem, and keeps them independent. Support us by purchasing Radicle or sponsoring us on GitHub — sponsors get access to our private Discord.
Example usage
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: roots/setup-trellis-cli@v1
with:
ansible-vault-password: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
repo-token: ${{ secrets.GITHUB_TOKEN }}
- run: trellis deploy production
See the examples for some full workflow examples including a site
with a Sage-based theme and a project
with a multi-repo setup.
See Workflow syntax for GitHub Actions for more details on writing GitHub workflows.
Setup
Inputs
ansible-vault-password
Required Ansible Vault password. Use a GitHub secret for this value (example in usage
above).
This can also be set using the GitHub CLI:
gh secret set ANSIBLE_VAULT_PASSWORD -b $(cat trellis/.vault_pass)
Note: this is a required input even if you don't use Ansible Vault. Just set
this to any random placeholder string.
repo-token
Optionally set the GitHub token for API authorization. Setting this token will avoid any potential API rate limits.
The best option is to set this to the default token secret which GitHub automatically sets: secrets.GITHUB_TOKEN.
See https://docs.github.com/en/actions/security-guides/automatic-token-authentication
auto-init
Whether to automatically run the trellis init command after install.
Default: true
If you want to manage dependencies manually yourself, disable this option.
cache-virtualenv
When enabled, the virtualenv created by the trellis init command is automatically
cached. The cache key includes the OS release, the path, full version and ABI of
python3, and the virtualenv's location, so an OS release change, a Python patch release
or a different workspace path starts a fresh cache rather than restoring a virtualenv built
for a different interpreter. A virtualenv that was not built by the current python3 is
not saved.
Default: true
galaxy-install
Whether to automatically run the trellis galaxy install command to install
Ansible Galaxy roles.
Default: true
trellis-directory
Path to the Trellis project directory. This defaults to trellis to match the default directory structure of a project created with trellis new.
Default: trellis
version
Version of Trellis CLI to install. See
Releases for all possible
versions.
Note: if you want a specific version, include the 'v' in the version name (eg:
v1.5.1).
Default: latest
SSH known hosts
Most usages of this action will require SSH known hosts to be set, including the example workflow which uses shimataro/ssh-key-action.
Since the GitHub Action runner will be the client SSHing into your remote Trellis server, this is needed to allow a connection from GitHub -> your server, which means the known host is for the remote server hostname.
This value is not just the hostname/IP, it needs be in OpenSSH format which looks like this:
example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
Or the hashed output:
|1|nLf9avvc+tz8nFgUW/3tPwjTA4Q=|dLZn1guXUrBjLg4s23ird724guA= ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
There's a few ways to get this value:
- using trellis-cli:
- manually using
ssh-keyscan:
ssh-keyscan -t ed25519 -H MY_SERVER_HOSTNAME
- from your
~/.ssh/known_hosts file (if you've previously SSH'd into the server):
Note: always use a GitHub secret to store this value. Do not hardcode the plain
text value in your workflow file. trellis key generate will use a secret
automatically.
Outputs
version
The Trellis CLI version installed. Example: v1.5.1
Community
Keep track of development and community news.