Skip to main content

Set up deployment

CI pushes to your extension's Drupal.org repository with an SSH key. Follow this page to create the key and the repository secrets that turn deployment on. Use a dedicated key for each project, so you can revoke 1 key and keep the others.

Before you start​

Make sure you have the following:

  • Administrator access to your extension's GitHub repository, to add secrets and variables.
  • A Drupal.org account that can push to your extension's repository.
  • ssh-keygen, which comes with OpenSSH.

Add the SSH key and the secrets​

  1. Generate a new SSH key:

    ssh-keygen -m PEM -t rsa -b 4096 -C "your_email+project_name@example.com"

    The -C comment only labels the key, so any text you'll recognize works.

  2. When ssh-keygen asks where to save the key, it suggests id_rsa in your .ssh directory. To keep your existing keys, enter a new filename in that directory, such as id_rsa_myextension. ssh-keygen writes the private key to that file and the public key to the same name with .pub added.

  3. Press Enter at both passphrase prompts to leave the passphrase empty. CI can't type a passphrase.

  4. Add the public key to the SSH keys of your Drupal.org account, which live on git.drupalcode.org, Drupal.org's GitLab.

  5. Add the private key as the DEPLOY_SSH_KEY secret in your repository's Settings > Secrets and variables > Actions. Paste the whole file, from its -----BEGIN line to its -----END line.

  6. Add these secrets in the same place:

    • DEPLOY_REMOTE - your extension's Drupal.org repository, such as git@git.drupal.org:project/myextension.git. Until it's set, the Deploy job reports a notice and skips deployment.
    • DEPLOY_USER_NAME - the git user name on the CI runner, such as your name on Drupal.org. The deployment fails without it. The deployment makes no commits of its own, so this name appears in no commit on Drupal.org.
    • DEPLOY_USER_EMAIL - the git email address on the runner, such as your email address on Drupal.org. The deployment fails without it too.

  7. Optional: To push every deployed branch to 1 branch of the DEPLOY_REMOTE repository, add a repository variable named DEPLOY_BRANCH, set to that branch's name, such as 1.x. Add it under Settings > Secrets and variables > Actions > Variables, since it isn't a secret. Set it only when 1 branch deploys, because several branches would replace each other's code in that 1 destination branch. Without DEPLOY_BRANCH, each branch deploys to the branch of the same name. Tags deploy as tags either way.

Confirm that the Actions secrets of your repository list DEPLOY_SSH_KEY, DEPLOY_REMOTE, DEPLOY_USER_NAME and DEPLOY_USER_EMAIL. You add DEPLOY_PROCEED, the secret that turns the push on, after the test in the next section.

Confirm that it works​

Until the DEPLOY_PROCEED secret is 1, the Deploy job runs but stops before the push, so you can test it first:

  1. Push a commit to a branch that deploys, such as 1.x. Watch the Deploy workflow that starts after Test passes. The job ends with "Skip deployment because DEPLOY_PROCEED is not set to 1." That message means DEPLOY_REMOTE, DEPLOY_USER_NAME and DEPLOY_USER_EMAIL are set. The job connects to DEPLOY_REMOTE only after the next step.
  2. Add the DEPLOY_PROCEED secret, set to 1, in the same place as the other secrets.
  3. Push another commit to the branch. After Test passes, the Deploy job pushes it, and the commit appears in your Drupal.org repository.
Other destinations

DEPLOY_REMOTE can name any git remote that accepts the key, such as a mirror on another git host.

Next steps​