cromulus / dokku-github-deploy

dokku github-action

Official Github Action for deploying apps to a Dokku installation

Requirements

Please note that this action is compatible with dokku >= 0.11.6.

Inputs

• branch: (optional) The branch to deploy when pushing to Dokku. Useful when a custom deploy branch is set on Dokku.

  • default: master
  • example value: main

• ci_branch_name: (optional) The branch name that triggered the deploy. Automatically detected from GITHUB_REF.

  • example value: develop

• ci_commit: (optional) The commit sha that will be pushed. Automatically detected from GITHUB_SHA.

  • example value: 0aa00d8dd7c971c121e3d1e471d0a35e1daf8abe

• command: (optional) The command to run for the action.

  • default: deploy
  • valid values:
    • deploy
    • review-apps:create: Used to create a review app - via dokku apps:clone - based on the appname configured in the git_remote_url. If the review app already exists, this action will not recreate the app. In both cases, the current commit will be pushed to the review app.
    • review-apps:destroy: Destroys an existing review app.

• deploy_docker_image: (optional) A docker image to deploy via git:from-image.

  • example value: dokku/test-app:1

• deploy_user_name: (optional) A username to use when deploying a docker image

• deploy_user_email: (optional) The email to use when deploying a docker image.

• git_push_flags: (optional) A string containing a set of flags to set on push. This may be used to enable force pushes, or trigger verbose log output from git.

  • example value: --force -vvv

• git_remote_url: (required) The dokku app's git repository url in SSH format.

  • example value: ssh://[e-mail]:22/appname

• review_app_name: (optional) The name of the review app to create or destroy. Computed as review-$APPNAME-$BRANCH_NAME if not specified, where:

  $APPNAME: The parsed app name from the `git_remote_url`
  $BRANCH_NAME: The inflected git branch name
  

  • example value: review-appname

• ssh_host_key: (optional) The results of running ssh-keyscan -t rsa $HOST. The github-action will otherwise generate this on the fly via ssh-keyscan.

  • example value:

    # dokku.com:22 SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.1
    dokku.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCvS+lK38EEMdHGb...
    

• ssh_private_key: (required) A private ssh key that has push access to the Dokku instance.

  • tip: It is recommended to use Encrypted Secrets to store sensitive information such as SSH Keys.

  • example value:

    -----BEGIN OPENSSH PRIVATE KEY-----
    MIIEogIBAAKCAQEAjLdCs9kQkimyfOSa8IfXf4gmexWWv6o/IcjmfC6YD9LEC4He
    qPPZtAKoonmd86k8jbrSbNZ/4OBelbYO0pmED90xyFRLlzLr/99ZcBtilQ33MNAh
    ...
    SvhOFcCPizxFeuuJGYQhNlxVBWPj1Jl6ni6rBoHmbBhZCPCnhmenlBPVJcnUczyy
    zrrvVLniH+UTjreQkhbFVqLPnL44+LIo30/oQJPISLxMYmZnuwudPN6O6ubyb8MK
    -----END OPENSSH PRIVATE KEY-----
    

Examples

All examples below are functionally complete and can be copy-pasted into a .github/workflows/deploy.yaml file, with some minor caveats:

• The git_remote_url should be changed to match the server and app.
• An Encrypted Secret should be set on the Github repository with the name SSH_PRIVATE_KEY containing the contents of a private ssh key that has been added to the Dokku installation via the dokku ssh-keys:add command.
• As pushing a git repository from a shallow clone does not work, all repository checkous should use a fetch-depth of 0. All examples below have this option set correctly.

For simplicity, each example is standalone, but may be combined as necessary to create the desired effect.

• Simple Example: Deploys a codebase on push or merge to master.

• Build in CI and Deploy an image: Builds a docker image in CI, pushes the image to the remote Docker Hub repository, and then notifies Dokku to deploy the built image.

• Cancel previous runs on new push: This workflow is particularly useful when triggered by new pushes, and utilizes a third-party action.

• Avoid SSH Host Keyscan: By default, this action will scan the host for it's SSH host key and use that value directly. This may not be desirable for security compliance reasons.

  The SSH_HOST_KEY value can be retrieved by calling ssh-keyscan -t rsa $HOST, where $HOST is the Dokku server's hostname.

• Specify a custom deploy branch: Certain Dokku installations may use custom deploy branches other than master. In the following example, we push to the develop branch.

• Verbose Push Logging: Verbose client-side logging may be enabled with this method. Note that this does not enable trace mode on the deploy, and simply tells the git client to enable verbose log output

• Force Pushing: If the remote app has been previously pushed manually from a location other than CI, it may be necessary to enable force pushing to avoid git errors.

• Review Apps: Handles creation and deletion of review apps through use of dokku apps:clone and dokku apps:destroy. Review apps are a great way to allow folks to preview pull request changes before they get merged to production.

  • Placing a shell script at bin/ci-pre-deploy can be used to reconfigure the app, as shown in this example.