Official Github Action for deploying apps to a Dokku installation
Please note that this action is compatible with dokku >= 0.11.6.
-
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
- default:
-
ci_branch_name: (optional) The branch name that triggered the deploy. Automatically detected fromGITHUB_REF.- example value:
develop
- example value:
-
ci_commit: (optional) The commit sha that will be pushed. Automatically detected fromGITHUB_SHA.- example value:
0aa00d8dd7c971c121e3d1e471d0a35e1daf8abe
- example value:
-
command: (optional) The command to run for the action.- default:
deploy - valid values:
deployreview-apps:create: Used to create a review app - viadokku apps:clone- based on theappnameconfigured in thegit_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.
- default:
-
deploy_docker_image: (optional) A docker image to deploy viagit:from-image.- example value:
dokku/test-app:1
- example value:
-
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
- example value:
-
git_remote_url: (required) The dokku app's git repository url in SSH format.- example value:
ssh://dokku@dokku.myhost.ca:22/appname
- example value:
-
review_app_name: (optional) The name of the review app to create or destroy. Computed asreview-$APPNAME-$BRANCH_NAMEif not specified, where:$APPNAME: The parsed app name from the `git_remote_url` $BRANCH_NAME: The inflected git branch name- example value:
review-appname
- example value:
-
ssh_host_key: (optional) The results of runningssh-keyscan -t rsa $HOST. The github-action will otherwise generate this on the fly viassh-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-----
-
-
ssh_passphrase: (optional) Passphrase to use when interacting with an SSH key that has a passphrase- example value:
password
- example value:
-
trace: (optional) Allows users to debug what the action is performing by enabling shell trace mode- example value:
1
- example value:
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_urlshould be changed to match the server and app. - An Encrypted Secret should be set on the Github repository with the name
SSH_PRIVATE_KEYcontaining the contents of a private ssh key that has been added to the Dokku installation via thedokku ssh-keys:addcommand. - As pushing a git repository from a shallow clone does not work, all repository checkous should use a
fetch-depthof0. 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_KEYvalue can be retrieved by callingssh-keyscan -t rsa $HOST, where$HOSTis 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 thedevelopbranch. -
Verbose Push Logging: Verbose client-side logging may be enabled with this method, as well as trace mode for all shell command output. Note that this does not enable trace mode on the remote deploy, and simply tells the
gitclient 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:cloneanddokku 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-deploycan be used to reconfigure the app, as shown in this example.
- Placing a shell script at