diff --git a/docs/deployment/continuous-integration/gitlab-ci.md b/docs/deployment/continuous-integration/gitlab-ci.md index 878b709bb..29b8c917e 100644 --- a/docs/deployment/continuous-integration/gitlab-ci.md +++ b/docs/deployment/continuous-integration/gitlab-ci.md @@ -1,108 +1,25 @@ # Gitlab CI -Gitlab-CI can be used to automatically deploy a Dokku application using the [ilyasemenov/gitlab-ci-git-push image](https://github.com/IlyaSemenov/gitlab-ci-git-push) docker image. +Gitlab-CI can be used to automatically deploy a Dokku application via the official the [dokku/ci-docker-image](https://github.com/dokku/ci-docker-image). The simplest example is as follows: -## Prerequisites +``` +--- +image: dokku/ci-docker-image -Make sure you have a Gitlab account and a Dokku project hosted on Gitlab. This method works whether if you are using buildpacks or Dockerfile. - -Make sure you have set up an app on the remote machine following [these instructions](http://dokku.viewdocs.io/dokku/deployment/application-deployment/) and can successfully deploy to it from the local machine. - -## Deploy automatically to production - -### Add 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 that `SSH_PRIVATE_KEY` is not available on merge requests or tests) -- Protected: Do not check this checkbox unless you know what you are doing - -### Add CI script - -Create a file named `.gitlab-ci.yml` at the root directory of the repository with the following contents: - -```yaml stages: - deploy variables: - APP_NAME: node-js-app + GIT_DEPTH: 0 deploy: - image: ilyasemenov/gitlab-ci-git-push stage: deploy - environment: - name: production - url: https://$APP_NAME.dokku.me/ only: - master - script: - - git-push ssh://dokku@dokku.me:22/$APP_NAME -``` - -You will need to modify the `APP_NAME` variable to the correct value for your application name. - -Running `git push origin master` will now trigger a gitlab-ci pipeline that will automatically deploy your application to your Dokku server. Go to your project on Gitlab and visit "Project > Pipelines" to see the deployment log. - - -## Review Applications - -One useful feature of gitlab is to be able to create review applications for non-production branches. This allows teams to review changes _before_ they are pushed to production. First, recreate the `SSH_PRIVATE_KEY` secret - do not delete the existing secret - but scoped to the `review/*` environment. This will allow non-production gitlab environments access to the secret. - -Next, we'll need to create the `review_app` gitlab job in our `.gitlab-ci.yaml`. - -```yaml -review_app: - image: ilyasemenov/gitlab-ci-git-push - stage: deploy - environment: - name: review/$CI_COMMIT_REF_NAME - url: https://$CI_ENVIRONMENT_SLUG.dokku.me/ - on_stop: stop_review_app - only: - - branches - except: - - master - script: - - mkdir -p ~/.ssh && echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa - - ssh-keyscan -H 22 "dokku.me" >> ~/.ssh/known_hosts - - ssh -t dokku@dokku.me -- apps:clone --ignore-existing --skip-deploy "$APP_NAME" "$CI_ENVIRONMENT_SLUG" - - git-push ssh://dokku@dokku.me:22/$CI_ENVIRONMENT_SLUG -``` - -The first two lines ensure that Gitlab can talk to the Dokku server. Next, we take advantage of the `apps:clone` command, and clone the existing application and all of it's configuration to a new location. If the new application already exists, the third line of the `script` step will be ignored. We also ignore the first deploy script to speed up the cloning process. Finally, the fourth line of the `script` step will deploy the code as normal. - -The above only runs for non-master branches, and will _also_ trigger an `on_stop` job called `stop_review_app`. When the branch is deleted or the code is merged, the `stop_review_app` job will be triggered. - -```yaml -stop_review_app: - image: ilyasemenov/gitlab-ci-git-push - stage: deploy variables: - GIT_STRATEGY: none - environment: - name: review/$CI_COMMIT_REF_NAME - action: stop - when: manual - script: - - mkdir -p ~/.ssh && echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa - - ssh-keyscan -H 22 "dokku.me" >> ~/.ssh/known_hosts - - ssh -t dokku@dokku.me -- --force apps:destroy "$CI_ENVIRONMENT_SLUG" + GIT_REMOTE_URL: ssh://dokku@dokku.me:22/appname + script: dokku-deploy + after_script: dokku-unlock ``` -The `stop_review_app` step will delete the temporary application, cleaning up now unused server resources. - -Going further, the following modifications can be done: - -- Notify via chat whenever a review application is created/destroyed. -- Push to a separate, staging server as opposed to a production server. -- Clone a "staging" application so that review applications do not affect production datasets. +For further usage documentation and other advanced examples, see Dokku's [gitlab-ci](https://github.com/dokku/gitlab-ci) repository.