gitlab-ci lint tool for validating `.gitlab-ci.yml` using Gitlab API
2.4K
Goodbye "yaml invalid" pipeline errors, and don't come back!
This tool use the Gitlab API to validate your local .gitlab-ci.yml.
It can be installed as a git pre-commit hook, preventing commit (and so push) of an invalid .gitlab-ci.yml.
The tool itself does not lint anything: it uses the lint API of a Gitlab instance => it needs to be run somewhere with an access to the Gitlab instance where your project come from.
docker pull orobardet/gitlab-ci-linter
None.
You don't even need a Git client.
The only thing required is a network connection to the Gitlab instance you are using in the repository you want to check.
And a git repository to check of course, having an origin remote corresponding to a Gitlab instance and a .gitlab-ci.yml file.
Once installed.
To do once per computer/environment you install the tool.
api scope.cd to a git repository having gitlab.com as origin remote (with https or ssh).docker run --rm -it -e "GCL_PERSONAL_ACCESS_TOKEN=<YOUR_PERSONAL_ACCESS_TOKEN>" -v $(PWD):/src -w /src orobardet/gitlab-ci-linter to check the validity of your .gitlab-ci-lintDeclare an alias gcl in your shell to invoke the tool even quicker.
.gitlab-ci.yml is detected in the git repository root, the tool does nothing (if installed as pre-commit hook, it will not prevent the commit).origin to guess the url of the Gitlab to use, and the project path (also works if the remote is ssh, as soon as the Gitlab respond on HTTP using the same FQDN as ssh)projects/:project_path_or_id/ci/lint API is not publicly accessible (or 2FA is enforced), you can specify a personal access token using --personal-access-token|-p option or GCL_PERSONAL_ACCESS_TOKEN environment variable. The token must have the api scope.--netrc|-n to try getting the token from the .netrc file (by default ~/.netrc on *nix, $HOME/_netrc on Windows), but not the token must be set
on the account field, not password (to prevent conflict with basic auth). login is not used.
e.g.: for gitlab.com, the .netrc entry should be:
machine gitlab.com
# possible login and password definition
account MY_PERSONAL_ACCESS_TOKEN
default entry of .netrc is ignored./ci/lint API endpoint was deprecated in v15.7 and removed in v16.0. Now, projects/:project_path_or_id/ci/lint is used instead.
The tool will try by default to guess the project path from your remote, but you can specify:
--project-path|-P option or CI_PROJECT_ID environment variable (predefined in Gitlab CI).--project-id|-I option or CI_PROJECT_PATH environment variable (predefined in Gitlab CI).
--project-id has precedence over --project-path.A bunch of options are available to configure the tool. All options can be also set using environment variables.
Option's value on the command line have precedence over environment variables.
Usage:
gitlab-ci-linter [global options] [command [command options]] [PATH]
The used Gitlab API is tied to a Gitlab project. Thus, the tools needs to know which Gitlab project (on which Gitlab instance) it has to target.
By default, it will try to autodetect from the 'origin' remote configured in the git repository (if any), by extracting the FQDN as the root URL,
and the project path. Works for 'http'' or 'ssh' remotes. e.g.: a remote "https://gitlab.com/orobardet/gitlab-ci-linter.git" or
"[email protected]:orobardet/gitlab-ci-linter.git" will target the API of the project "orobardet/gitlab-ci-linter" on "https://gitlab.com".
In case the auto-detection does not work, or you don't have a compatible remote, or you want to target another project, you can specify the Gitlab
root URL using '-gitlab-url|-u' flag, and the project using '--project-path|-P' or '--project-id|-I' flags. '--project-id' has precedence over '--project-path'.
If your gitlab instance or project needs an authentification (which is the case on gitlab.com), you have to specify a personal access token with '--personal-access-token|-p'.
You can also use the flag '--netrc|-n' to try getting the token from the .netrc file (by default ~/.netrc on *nix, $HOME/_netrc on Windows), but not the token must be set
on the 'account' field, not 'password' (to prevent conflict with basic auth). Also, the 'default' entry of .netrc is ignored.
e.g.: for gitlab.com, the .netrc entry should be:
machine gitlab.com
# possible login and password definition
account MY_PERSONAL_ACCESS_TOKEN
Global options:
--gitlab-url URL, -u URL root URL of the Gitlab instance to use API (default: auto-detect from remote origin, else "https://gitlab.com") [$GCL_GITLAB_URL]
--ci-file FILE, -f FILE FILE is the relative or absolute path to the gitlab-ci file [$GCL_GITLAB_CI_FILE]
--directory DIR, -d DIR DIR is the directory from where to search for gitlab-ci file and git repository (default: ".") [$GCL_DIRECTORY]
--personal-access-token TOK, -p TOK personal access token TOK for accessing repositories when you have 2FA enabled. Has precedence over .netrc usage [$GCL_PERSONAL_ACCESS_TOKEN]
--netrc, -n Try to get personal access token as 'account' from .netrc file (default: false) [$GCL_NETRC]
--netrc-file value Path of .netrc file to use. By default, try to detect it. [$GCL_NETRC_FILE]
--project-path PATH, -P PATH PATH of the GitLab project that is used in the API for Gitlab >=13.6. Has precedence over path guessing from remote [$CI_PROJECT_PATH, $GCL_PROJECT_PATH]
--project-id ID, -I ID ID of the GitLab project that is used in the API for Gitlab >=13.6. Has precedence over --project-path [$CI_PROJECT_ID, $GCL_PROJECT_ID]
--timeout value, -t value timeout in second after which http request to Gitlab API will timeout (and the program will fails) (default: 15) [$GCL_TIMEOUT]
--no-color don't color output. By defaults the output is colorized if a compatible terminal is detected. (default: false) [$GCL_NOCOLOR]
--verbose, -v verbose mode (default: false) [$GCL_VERBOSE]
--merged-yaml, -m include merged yaml in response (default: false) [$GCL_INCLUDE_MERGED_YAML]
--help, -h show help
--version print the version information (default: false)
Arguments:
If PATH if given, it will depending of its type on filesystem:
- if a file, it will be used as the gitlab-ci file to check (similar to global --ci-file option)
- if a directory, it will be used as the folder from where to search for a ci file and a git repository (similar to global --directory option)
PATH have precedence over --ci-file and --directory options.
Commands:
check, c Check the .gitlab-ci.yml (default command if none is given)
install, i install as git pre-commit hook
uninstall, u uninstall the git pre-commit hook
version, v Print the version information
help, h Shows a list of commands or help for one command
If no command is given, 'check 'is used by default
Content type
Image
Digest
sha256:c836ae851…
Size
6.8 MB
Last updated
over 1 year ago
docker pull orobardet/gitlab-ci-linter