How can I test gitlab-ci.yml?

The correct answer is that you cannot test your build pipeline without committing source code to your repository. You can only test one job - most likely the first job - of your build pipeline with gitlab-runner exec.

Since you cannot run multiple jobs you cannot chain any prepare or build steps with anything else. There is no way to stop gitlab-runner from creating a clean checkout and destroying your prepare/build steps.

The best/only way to test is to create a branch and keep force pushing changes to .gitlab-ci.yml to it.

If you want to go beyond mere linting and actually run your CI script, you can do so using gitlab-runner. Here's how to do it.

Install gitlab-runner

OS=darwin
#OS=linux # Uncomment on linux
sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-${OS}-amd64
sudo chmod +x /usr/local/bin/gitlab-runner

^{Official gitlab-runner docs here}

Create a command

The following .gitlab-ci.yml file defines a task named build:

build:
  script:
    - echo "Hello World"

Run the command locally ^{(limitations apply!)}

gitlab-runner exec shell build

When I run the above locally, I get the following output:

Running with gitlab-runner 11.3.1~beta.4.g0aa5179e (0aa5179e)
Using Shell executor...
Running on cory-klein.local...
Cloning repository...
Cloning into '/Users/coryklein/code/prometheus-redis-exporter/builds/0/project-0'...
done.
Checking out 66fff899 as master...
Skipping Git submodules setup
$ echo "Hello World"
Hello World
Job succeeded

You can run builds locally (if you control the runner that is) by using the gitlab-runner exec command as described in the official docs here.

Make sure you also check the limitations of testing jobs this way.

For the record: You can also copy paste your gitlab-ci.yml into the linter-form provided by gitlab:

Depending on which IDE you are using you might be able to find plugins that check for validity. For example in VS Code you can use a plugin called gitlab-vscode-extension which can validate your .gitlab-ci.yml file.

In case you want to programatically validate your .gitlab-ci.yml, gitlab provides an API which allows you to POST your yml to /ci/lint, e.g.:

curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'