A collection of gitlab-ci examples
Please note that these workflows are compatible with dokku >= 0.11.6
.
All examples require a SSH_PRIVATE_KEY
environment variable set for the Gitlab CI pipeline. This may be set via a "secret variable"
Browse to the repository in question and visit the following path: the Gitlab project > Settings > CI/CD.
Click on Secret variables > Expand
and fill in the blanks.
-
Key:
SSH_PRIVATE_KEY
-
Value: paste in an SSH private key registered in Dokku:
-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
-
Environment scope:
production
(This make sure thatSSH_PRIVATE_KEY
is not available on merge requests or tests) -
Protected: Do not check this checkbox unless you know what you are doing
-
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 fromCI_COMMIT_REF_NAME
.- example value:
develop
- example value:
-
CI_COMMIT
: (optional) The commit sha that will be pushed. Automatically detected fromCI_COMMIT_SHA
.- example value:
0aa00d8dd7c971c121e3d1e471d0a35e1daf8abe
- example value:
-
COMMAND
: (optional) The command to run for the action.- default:
deploy
- valid values:
deploy
review-apps:create
: Used to create a review app - viadokku apps:clone
- based on theappname
configured 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:
-
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_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
- 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-----
-
All examples below are functionally complete and can be copy-pasted into a .gitlab-ci.yml
file, with some minor caveats:
- The
GIT_REMOTE_URL
should be changed to match the server and app. - An Gitlab Variable should be set on the Gitlab repository with the name
SSH_PRIVATE_KEY
containing the contents of a private ssh key that has been added to the Dokku installation via thedokku ssh-keys:add
command. - As pushing a git repository from a shallow clone does not work, all repository checkouts should use a
GIT_DEPTH
of0
. 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 pipeline is particularly useful when triggered by new pushes.
-
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 callingssh-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 thedevelop
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
anddokku apps:destroy
. Review apps are a great way to allow folks to preview pull request changes before they get merged to production.