Tired of pushing to test your .gitlab-ci.yml?
Run gitlab pipelines locally as shell executor or docker executor.
Get rid of all those dev specific shell scripts and make files.
Table of contents
Installation
NPM
npm install -g gitlab-ci-local
Linux
curl -s "https://firecow.github.io/gitlab-ci-local/ppa/pubkey.gpg" | sudo apt-key add -
sudo curl -s -o /etc/apt/sources.list.d/gitlab-ci-local.list "https://firecow.github.io/gitlab-ci-local/ppa/gitlab-ci-local.list"
sudo apt-get update
sudo apt-get install gitlab-ci-local
Macos
brew install gitlab-ci-local
Windows (Git bash)
Install gitbash
Download and put binary in C:\Program Files\Git\mingw64\bin
curl -L https://github.com/firecow/gitlab-ci-local/releases/latest/download/win.gz | gunzip -c > /c/Program\ Files/Git/mingw64/bin/gitlab-ci-local.exe
Convenience
DotEnv file
Add a .gitlab-ci-local-env
file to the current working directory
# Overrides .gitlab-ci.yml as the default git ci/cd file
FILE=doctor-strange.yml # --file
# Always runs needed jobs, when gitlab-ci-local <job-name> is called
NEEDS=true # --needs
All cli options can be assigned default values this way
Bash alias
echo "alias gcl='gitlab-ci-local'" >> ~/.bashrc
Tab completion
gitlab-ci-local --completion >> ~/.bashrc
Quirks
Tracked Files
Untracked and ignored files will not be synced inside isolated jobs, only tracked files are synced.
Remember git add
Home variables
Put a file like this in $HOME/.gitlab-ci-local/variables.yml
---
project:
gitlab.com/test-group/test-project.git:
# Will be type Variable and only available if remote is exact match
AUTHORIZATION_PASSWORD: djwqiod910321
gitlab.com:project/test-group/test-project.git: # another syntax
AUTHORIZATION_PASSWORD: djwqiod910321
group:
gitlab.com/test-group/:
# Will be type Variable and only available for remotes that include group named 'test-group'
DOCKER_LOGIN_PASSWORD: dij3213n123n12in3
global:
# Will be type File, because value is a file path
KNOWN_HOSTS: '~/.ssh/known_hosts'
DEPLOY_ENV_SPECIFIC:
type: variable # Optional and defaults to variable
values:
'*production*': 'Im production only value'
'staging': 'Im staging only value'
FILE_CONTENT_IN_VALLUES:
type: file
values:
'*': |
Im staging only value
I'm great for certs n' stuff
Variables will now appear in your jobs, if project or group matches git remote, global's are always present
Remote file variables
gitlab-ci-local --remote-variables git@gitlab.com:firecow/example.git=gitlab-variables.yml=master
Project variables
Put a file like this in $CWD/.gitlab-ci-local-variables.yml
---
AUTHORIZATION_PASSWORD: djwqiod910321
DOCKER_LOGIN_PASSWORD: dij3213n123n12in3
# Will be type File, because value is a file path
KNOWN_HOSTS: '~/.ssh/known_hosts'
Variables will now appear in your jobs.
Decorators
@Description
decorator
The Adds descriptive text to gitlab-ci-local --list
# @Description Install npm packages
npm-install:
image: node
artifacts:
paths:
- node_modules/
script:
- npm install --no-audit
@Interactive
decorator
The # @Interactive
interactive-shell:
rules:
- if: $GITLAB_CI == 'false'
when: manual
script:
- docker run -it debian bash
@InjectSSHAgent
decorator
The # @InjectSSHAgent
need-ssh:
image: kroniak/ssh-client
script:
- ssh-add -L
@NoArtifactsToSource
decorator
The Prevent artifacts from being copied to source folder
# @NoArtifactsToSource
produce:
stage: build
script: mkdir -p path/ && touch path/file1
artifacts: { paths: [path/] }
Includes
Includes from external sources are only fetched once. Use --fetch-includes
to invoke an external fetching rutine.
Artifacts
Shell executor jobs copies artifacts to host/cwd directory. Use --shell-isolation option to mimic correct artifact handling for shell jobs.
Docker executor copies artifacts to and from .gitlab-ci-local/artifacts
Development
You need nodejs 16+
Scripts
npm install
npm run build
npm run test
Package binaries
npm run pkg-linux
npm run pkg-win
npm run pkg-macos
npm run pkg-all