Deploy over SSH

Cloud

Server v4.x

Server v3.x

1. Add SSH key for target

Add the SSH key for the target to which you are deploying (these instructions are for cloud, server v3.x, and server v4.x).

In a terminal, generate the key with ssh-keygen -t ed25519 -C "your_email@example.com". See Secure Shell documentation for additional details.
In the CircleCI application, go to your project’s settings by clicking the the Project Settings button (top-right on the Pipelines page of the project).
On the Project Settings page, click on SSH Keys.
Scroll down to the Additional SSH Keys section.
Click the Add SSH Key button.
In the Hostname field, enter the key’s associated host (for example, git.heroku.com). If you do not specify a hostname, the key will be used for all hosts.
In the Private Key field, paste the SSH key you are adding.
Click the Add SSH Key button.

For additional context, see the Adding an SSH Key to CircleCI page.

2. Add the SSH username and hostname

Add the SSH username and SSH hostname of your build VM as environment variables. For instructions, see the Set an environment variable in a project page. In this example, these variables are defined as SSH_USER and SSH_HOST, respectively.

3. Create a deploy job

In your .circleci/config.yml, create a deploy job and add a command to deploy the main branch.

version: 2.1

jobs:
  build:
  #...
  deploy:
    machine:
      image: ubuntu-2204:2023.07.2
    steps:
      - run:
          name: Deploy Over SSH
          command: |
            ssh $SSH_USER@$SSH_HOST "<remote deploy command>"

workflows:
  build-and-deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build # only deploy once build job has completed
          filters:
            branches:
              only: main # only deploy on the main branch

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.