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 (default to master). Useful when a custom deploy branch is set on Dokku.

Example Value: develop

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://[email protected]:22/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

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

Required. A private ssh key that has push access to the Dokku instance.

Example Value:

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

Arguments

Arguments are optional, but may change the behavior of the action when specified. The following are the currently supported arguments and examples on how to specify them.

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. Takes a second required argument as the name of the review app to create.

Example:

args: review-apps:create appname-${{ github.event.pull_request.number }}

review-apps:destroy

Destroys a review app. Takes a second required argument as the name of the review app to destroy.

Example:

args: review-apps:destroy appname-${{ github.event.pull_request.number }}

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.

• 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.