Skip to content

Announcing Enhanced VCS Integration 🎉 🎉

Read more here →

Getting Started»


To follow this tutorial, you should have an EC2 instance together with an SSH private key that can be used to access the instance ready.

Initial Setup»

Start by forking our Ansible example repository

Looking at the code, you'll find that it configures a simple Apache HTTP Server on an EC2 instance. We are also using the AWS EC2 inventory plugin to find the hosts to configure. Feel free to modify aws_ec2.yml inventory file to fit your needs.

Also, please take notice of the Spacelift runtime config file, that defines the runner image used on this stack and the ANSIBLE_CONFIG environment variable. Remember you can always define runner image in stack settings, and environment variables within environment settings.

Creating a stack»

In Spacelift, go ahead and click the Add Stack button to create a Stack in Spacelift.

In the first tab, you should select the repository you've just forked, as can be seen in the picture.

Configuring the VCS settings.

In the next tab, you should choose the Ansible backend. There, fill in the Playbook field with the playbook you want to run. In the case of our example, it is playbook.yml. You could also configure an option to skip the planning phase, but we will leave that disabled for now.

Configuring the backend settings.

On the next tab (Define Behavior), setting up a runner image with Ansible dependencies is required. You may use your image (with the Ansible version you choose and all the required dependencies) or use one of our default ones. In this example we are using an AWS-based runner image defined in the runtime configuration file:

If you have a private worker pool you'd like to use, you can specify it there instead of the default public one as well.

Finally, choose a name for your Spacelift Stack on the last page. We'll use Ansible Example again.

Naming the Stack.

Our newly created Stack.

Triggering the Stack»

Making sure the inventory plugin works»

You can now click Trigger to create a new Spacelift Run.

You should see the run finishing with no hosts matched. This is because the AWS EC2 inventory plugin did not detect valid AWS credentials.

Creating change set failed: Requires AWS configuration


You need to configure the AWS integration to give Spacelift access to your AWS account. You can find the details here.

Configuring SSH keys»

After triggering a run again, you will see we could successfully find EC2 hosts (provided they could be localized with aws_ec2.yml inventory file filters), but we cannot connect to them using SSH. The reason for that is we did not configure SSH keys yet.

Missing SSH key configuration

Let's configure the correct credentials using the Environment.

Go to the Environment tab and add the private key that can be used to access the machine as a secret mounted file.

Adding private key file

You should also specify the location of the SSH private key for Ansible, and you can do that using the ANSIBLE_PRIVATE_KEY_FILE environment variable.

Ansible stack environment with an SSH config

Investigating planned changes»

Triggering a run again, you should successfully see it get through the planning phase and end up in the unconfirmed state.

Ansible stack in an unconfirmed state

In the plan, you can see detailed information about each resource that is supposed to be created.

At this point, you can investigate the changes Ansible playbook will apply and to which hosts.

When you're happy with the planned changes, click Confirm to apply them.

Ansible stack finished a run

By now, the machine should be configured with a simple Apache HTTP server with a sample website on port 8000.

You can switch to the Resources tab to see the hosts you have configured, together with the history of when the host was last created and updated.

Exploring the created resources.


That's it! You can find more details about the available configuration settings in the reference. Apart from configuration options available within Spacelift remember you can configure Ansible however you'd like using native Ansible configuration capabilities.