The author has some repositories at GitLab. Occasionaly .gitlab-ci.yml files containing syntax errors would be committed accidentally, breaking the CI build.
GitLab provide a web form interface, available per project for linting. However, this started to be cumbersome and became a candidate for automation via the GitLab API and git hooks. Unfortunately, the free plan for gitlab.com does not feature pre-receive git server hooks which could prevent pushes containing invalid .gitlab-ci.yml files.
Git provides, a pre-commit hook that runs for staged files on the local development environment. While use of local git hooks are not easily enforced, it is better than the alternative in this case. The pre-commit project facilitates deployment and installation of client side git hooks.
The author developed a Ruby CLI and library to lint GitLab yaml files containing CI Pipeline specifications. Linting is performed using the GitLab API.
The gem is served on rubygems.org as gitlab-lint-client and the
source code, with accompanying unit and functional tests, are held within this repository.
It can be installed by issuing the following command:
gem install gitlab-lint-client
.
Usage details are provided with the help option of the CLI, glab-lint --help Examples are:
# mandatory options
glab-lint --yaml=.gitlab-ci.yml --base-url=https://gitlab.com
glab-lint -f .gitlab-ci.yml -u https://gitlab.com
# configure timeout in seconds, for API request
glab-lint --yaml=.gitlab-ci.yml --base-url=https://gitlab.com --timeout=10
glab-lint -f .gitlab-ci.yml -u https://gitlab.com -t 10
# display program version number and exit
glab-lint --version
glab-lint -v
The author is using the gem within a client side pre-commit hook to automate GitLab CI linting.
This repository specifies a pre-commit hook in the .pre-commit-hooks.yml file. Developers can configure their GitLab repositories to use this hook by creating a .pre-commit-config.yaml file in the root of their repository.
repos:
- repo: https://github.com/dcs3spp/validate-gitlab-ci
rev: v0.0.1
hooks:
- id: validate-gitlab-ci
args: [--yaml=.gitlab-ci.yml, --base-url=https://gitlab.com]
pass_filenames: false
types: [yaml]
files: .gitlab-ci.yml
stages: [commit]
Subsequently, install the pre-commit tool by issuing the following command:
pip install pre-commit
Instruct pre-commit to download and configure the hooks defined in the .pre-commit-config.yaml file:
pre-commit install
This will create a Ruby environment and automatically download and install the gem held within this repository. The environment is setup on first time use only.
Subsequently, whenever an attempt is made to commit the GitLab CI yaml file, the pre-commit hook will automatically send it for linting to the GitLab API. If a failed response is received from the API, then the commit is declined.
Perform a git clone:
git clone --depth 1 https://github.com/dcs3spp/validate-gitlab-ci.git
-
This will download the source to local machine.
-
Ruby >=2.3.6 is required with the following development dependencies:
- bundler
- pry
- rake
- rspec
- webmock
-
The gemspec file lists specific dependencies for development.
-
This gem is available publically as gitlab-lint-client
gem build gitlab-lint-client.gemspec
gem install gitlab-lint-client-0.0.1.gem
bundle exec rspec
Name | Description |
---|---|
GITLAB_API_TOKEN | GitLab API Token for use with private GitLab servers (other than https://gitlab.com) that may require an authorization header |
# build the gem
rake build
# install the gem
rake install
# run the tests
rake spec
# release the gem
rake release
The gem is available as open source under the terms of the MIT License.