@dathuis/gitlab-pipeline-locks

Setting up a pipeline to utilize BBDM

Disable pipeline merging

By default Gitlab enables a setting that merges pipelines together if one is pushed shortly after another. This needs to be disabled. To disable go to Project > Settings > CI / CD Settings. Expand "General Pipelines" and uncheck the box that says Auto-cancel redundant, pending pipelines

Gitlab Environment variables

Environment variables need to be set for the gitlab runners so that the BBDM endpoint and API key are accessible.

Two environment variables need to be set:

• PIPELINE_LOCKS_API_KEY - You can get this from the output of the serverless deploy script, or from API gateway in your AWS Account.
• PIPELINE_LOCKS_ENDPOINT - Endpoint created by AWS API Gateway. Also get from the output of the serverless deploy script or from your AWS console.

These can be set by going to the Gitlab project > Settings > CI / CD Settings > Environment Variables.

Docker image

The Gitlab runners need to use a docker image that has some scripts globally accessible. The DockerFile needs the following:

RUN npm install -g @dathuis/gitlab-pipeline-locks

Pipeline job setup

Jobs

A few extra pipeline jobs need to be added in the .gitlab-ci for this to work, these need to be added for each stage. This includes a new stage named registerDeploy which includes two jobs: registerDeploy and startDeploy. The name of each of these should be prefixed with the stage name. The next stage should contain one automatic job called deploy.

Each of these need to have the stage as a postfix. For example, if my stage name is Beta, I will have the following setup:

• registerDeployBeta
  • registerDeployBeta
  • startDeployBeta manual
• deployBeta
  • deployBeta

An environment variable called STAGE_NAME also needs to be accessible inside of the runner for each of these. In the example above each of the jobs needs STAGE_NAME=beta.

These should only run for the master branch, for this include:

only:
  - master

To include more stages, include the same jobs and stages as above for another stage and replace Beta with the name of that stage.

Scripts

Some scripts need to be utilized inside of these jobs.

register-deploy

This should be called as the only script inside of the registerDeploy job.

gitlab-pipeline-register-deploy

complete-deploy

This should be run as the last script in your deploy job. It sets the deployment status to complete and unlocks the stage for any incoming deployments.

gitlab-pipeline-complete-deploy

Teardown

The teardown script is optional, but useful depending on your setup. Our setup includes one pipeline stage that sets up an AWS stack and tests it. The next stage cleans up this AWS stack and always runs, regardless of failures. There is a problem when the deploy and test jobs fail and we want to restart the pipeline.

When restarting a pipeline only the failed jobs run, so the stack may be setup again and tests run again, but the teardown script does not run again. If you use this as the last script in the teardown stage it will check if the job before it in the pipeline succeeded or failed. If the job before failed, the teardown script will fail as well. This way if the pipeline is restarted, the teardown will always run again.

gitlab-pipeline-teardown

How it works

This service enables some assumptions:

• Only one deployment can happen at one time for one region
• Commits will only be deployed in order
• One deployment per commit

It does this by maintaining a dynamo table of statuses to manage the current status for each region in each project.

The registerDeploy Gitlab job makes a request to this service including the stage, project and commit ID. If this commit is next in line the service will start the manual startDeploy job which will unblock the pipeline and continue to the Deploy stage. If it is not next in line, it will not unblock, but the service will add any parent commits to a queue to ensure that it will be unblocked later once on of the parents have completed deploying.

If there are any problems and the current state of a project and stage needs to be overwritten, you can manually click start on the startDeploy job. The status of the stage will be reset after the deploy completes successfully.

Setting up pipeline locks/BBDM

Gitlab permissions

In order for BBDM to work it needs to be able to call the Gitlab API for the gitlab endpoing that you use. This needs to be used as an environment variable when deploying the serverless stack. To do this go to your Gitlab settings page then Access Tokens. From thisp age you can create a Personal Access Token. Cereate one and then save the API key somewhere for use later.

Deploying

To deploy, clone the repository then run the following command:

GITLAB_URL=<GITLAB URL SUCH AS https://gitlab.dathuis.nl> GITLAB_API_KEY=<API KEY FROM PERSONAL TOKEN> sls deploy