Examples are a useful way of understanding how to implement GitLab CI/CD for your specific use case.
This page contains links to a variety of examples that can help you understand how to
implement [GitLab CI/CD](../README.md) for your specific use case.
Examples are available in several forms. As a collection of:
Examples are available in several forms. As a collection of:
-`.gitlab-ci.yml`[template files](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates) maintained in GitLab. When you create a new file via the UI,
-`.gitlab-ci.yml`[template files](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates) maintained in GitLab. When you create a new file via the UI,
GitLab will give you the option to choose one of these templates. This will allow you to quickly bootstrap your project for CI/CD.
GitLab will give you the option to choose one of these templates. This will allow you to quickly bootstrap your project for CI/CD.
If your favorite programming language or framework are missing, we would love your help by sending a merge request with a new `.gitlab-ci.yml` to this project.
If your favorite programming language or framework are missing, we would love your help by sending a merge request with a new `.gitlab-ci.yml` to this project.
- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs.
- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. Projects include demonstrations of [multi-project pipelines](https://gitlab.com/gitlab-examples/multi-project-pipelines) and using [Review Apps with a static site served by nginx](https://gitlab.com/gitlab-examples/review-apps-nginx/).
- Examples and [other resources](#other-resources) listed below.
- Examples and [other resources](#other-resources) listed below.
## CI/CD examples
## CI/CD examples
The following table lists examples for different use cases:
The following table lists examples with step-by-step tutorials that are contained in this section.
| Testing | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md). |
### Contributing examples
### Contributing examples
...
@@ -50,22 +45,21 @@ language users and GitLab by sending a merge request with a guide for that langu
...
@@ -50,22 +45,21 @@ language users and GitLab by sending a merge request with a guide for that langu
You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community-writers/)
You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community-writers/)
to get paid for writing complete articles for GitLab.
to get paid for writing complete articles for GitLab.
### Adding templates to your GitLab installation **[PREMIUM ONLY]**
## Adding templates to your GitLab installation **[PREMIUM ONLY]**
If you want to have customized examples and templates for your own self-managed GitLab instance available to your team, your GitLab administrator can [designate an instance template repository](https://docs.gitlab.com/ee/user/admin_area/settings/instance_template_repository.html) that contains examples and templates specific to your enterprise.
If you want to have customized examples and templates for your own self-managed GitLab instance available to your team, your GitLab administrator can [designate an instance template repository](https://docs.gitlab.com/ee/user/admin_area/settings/instance_template_repository.html) that contains examples and templates specific to your enterprise.
## Other resources
## Other resources
This section provides further resources to help you get familiar with different aspects of GitLab CI/CD.
This section provides further resources to help you get familiar with various uses of GitLab CI/CD.
Note that older articles and videos may not reflect the state of the latest GitLab release.
NOTE: **Note:**
These resources may no longer reflect the current state of GitLab CI/CD.
### CI/CD in the cloud
### CI/CD in the cloud
For examples of setting up GitLab CI/CD for cloud-based environments, see:
For examples of setting up GitLab CI/CD for cloud-based environments, see:
-[How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/)
-[How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/)
-[Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw)
-[How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/)
-[How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/)
-[How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/)
-[How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/)
...
@@ -83,7 +77,6 @@ For some examples to help get you started, see:
...
@@ -83,7 +77,6 @@ For some examples to help get you started, see:
@@ -16,8 +17,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory
...
@@ -16,8 +17,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory
You'll create two different projects:
You'll create two different projects:
-`simple-maven-dep`: the app built and deployed to Artifactory (available at <https://gitlab.com/gitlab-examples/maven/simple-maven-dep>)
-`simple-maven-dep`: the app built and deployed to Artifactory (see the [simple-maven-dep](https://gitlab.com/gitlab-examples/maven/simple-maven-dep) example project)
-`simple-maven-app`: the app using the previous one as a dependency (available at <https://gitlab.com/gitlab-examples/maven/simple-maven-app>)
-`simple-maven-app`: the app using the previous one as a dependency (see the [simple-maven-app](https://gitlab.com/gitlab-examples/maven/simple-maven-app) example project)
We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/product/continuous-integration/).
We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/product/continuous-integration/).
We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it.
We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it.
# Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD
# Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD
This guide covers the building dependencies of a PHP project while compiling assets via an NPM script.
This guide covers the building of dependencies of a PHP project while compiling assets via an NPM script using [GitLab CI/CD](../../README.md).
While is possible to create your own image with custom PHP and Node JS versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and NodeJS installed.
While it is possible to create your own image with custom PHP and Node JS versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and NodeJS installed.
```yaml
```yaml
image:tetraweb/php
image:tetraweb/php
...
@@ -46,9 +50,9 @@ To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitla
...
@@ -46,9 +50,9 @@ To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitla
### Security tip
### Security tip
Create a user that has access **only** to the folder that needs to be updated!
Create a user that has access **only** to the folder that needs to be updated.
After you create that variable, you need to make sure that key will be added to the docker container on run:
After you create that variable, you need to make sure that key will be added to the Docker container on run:
```yaml
```yaml
before_script:
before_script:
...
@@ -68,7 +72,7 @@ In order, this means that:
...
@@ -68,7 +72,7 @@ In order, this means that:
And this is basically all you need in the `before_script` section.
And this is basically all you need in the `before_script` section.
## How to deploy things
## How to deploy
As we stated above, we need to deploy the `build` folder from the docker image to our server. To do so, we create a new job:
As we stated above, we need to deploy the `build` folder from the docker image to our server. To do so, we create a new job:
...
@@ -93,7 +97,7 @@ Here's the breakdown:
...
@@ -93,7 +97,7 @@ Here's the breakdown:
1.`ssh-add ...` we will add that private key you added on the web UI to the docker container
1.`ssh-add ...` we will add that private key you added on the web UI to the docker container
1. We will connect via `ssh` and create a new `_tmp` folder
1. We will connect via `ssh` and create a new `_tmp` folder
1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder
1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder
1. We will connect again to`ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
1. We will connect again via`ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
1. We connect to ssh and remove the `_old` folder
1. We connect to ssh and remove the `_old` folder
What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed).
What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed).
...
@@ -109,14 +113,14 @@ If you're using this only for stage server, you could do this in two steps:
...
@@ -109,14 +113,14 @@ If you're using this only for stage server, you could do this in two steps:
The problem is that there will be a small period of time when you won't have the app on your server.
The problem is that there will be a small period of time when you won't have the app on your server.
So we use so many steps because we want to make sure that at any given time we have a functional app in place.
Therefore, for a production environment we use additional steps to ensure that at any given time, a functional app is in place.
## Where to go next
## Where to go next
Since this was a WordPress project, I gave real life code snippets. Some ideas you can pursuit:
Since this was a WordPress project, I gave real life code snippets. Some further ideas you can pursue:
- Having a slightly different script for `master` branch will allow you to deploy to a production server from that branch and to a stage server from any other branches;
- Having a slightly different script for `master` branch will allow you to deploy to a production server from that branch and to a stage server from any other branches.
- Instead of pushing it live, you can push it to WordPress official repo (with creating a SVN commit & stuff);
- Instead of pushing it live, you can push it to WordPress official repo (with creating a SVN commit, etc.).
- You could generate i18n text domains on the fly.
- You could generate i18n text domains on the fly.
# Test and deploy a Python application with GitLab CI/CD
# Test and deploy a Python application with GitLab CI/CD
This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
You can checkout the [example source](https://gitlab.com/ayufan/python-getting-started).
You can also view or fork the complete [example source](https://gitlab.com/ayufan/python-getting-started).
## Configure project
## Configure project
...
@@ -46,9 +50,9 @@ production:
...
@@ -46,9 +50,9 @@ production:
This project has three jobs:
This project has three jobs:
-`test` - used to test Django application,
-`test` - used to test Django application.
-`staging` - used to automatically deploy staging environment every push to `master` branch
-`staging` - used to automatically deploy staging environment every push to `master` branch.
-`production` - used to automatically deploy production environment for every created tag
-`production` - used to automatically deploy production environment for every created tag.
## Store API keys
## Store API keys
...
@@ -67,8 +71,9 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/).
...
@@ -67,8 +71,9 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/).
## Create Runner
## Create Runner
First install [Docker Engine](https://docs.docker.com/installation/).
First install [Docker Engine](https://docs.docker.com/installation/).
To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner).
To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner).
You can use public runners available on `gitlab.com`, but you can register your own:
You can use public runners available on `gitlab.com` or you can register your own:
```sh
```sh
gitlab-runner register \
gitlab-runner register \
...
@@ -81,6 +86,6 @@ gitlab-runner register \
...
@@ -81,6 +86,6 @@ gitlab-runner register \
--docker-postgres latest
--docker-postgres latest
```
```
With the command above, you create a runner that uses [python:3.5](https://hub.docker.com/r/_/python/) image and uses[postgres](https://hub.docker.com/r/_/postgres/) database.
With the command above, you create a runner that uses the [python:3.5](https://hub.docker.com/r/_/python/) image and uses a[postgres](https://hub.docker.com/r/_/postgres/) database.
To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password.
# Test and deploy a Ruby application with GitLab CI/CD
# Test and deploy a Ruby application with GitLab CI/CD
This example will guide you how to run tests in your Ruby on Rails application and deploy it automatically as Heroku application.
This example will guide you through how to run tests in your Ruby on Rails application and deploy it automatically as a Heroku application.
You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all).
You can also view or fork the complete [example source](https://gitlab.com/ayufan/ruby-getting-started) and view the logs of its past [CI jobs](https://gitlab.com/ayufan/ruby-getting-started/-/jobs?scope=finished).
## Configure the project
## Configure the project
...
@@ -53,13 +57,14 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun
...
@@ -53,13 +57,14 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun
## Create Heroku application
## Create Heroku application
For each of your environments, you'll need to create a new Heroku application.
For each of your environments, you'll need to create a new Heroku application.
You can do this through the [Dashboard](https://dashboard.heroku.com/).
You can do this through the [Heroku Dashboard](https://dashboard.heroku.com/).
## Create Runner
## Create Runner
First install [Docker Engine](https://docs.docker.com/installation/).
First install [Docker Engine](https://docs.docker.com/installation/).
To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner/).
To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner/).
You can use public runners available on `gitlab.com`, but you can register your own:
You can use public runners available on `gitlab.com` or register your own:
```sh
```sh
gitlab-runner register \
gitlab-runner register \
...
@@ -72,6 +77,6 @@ gitlab-runner register \
...
@@ -72,6 +77,6 @@ gitlab-runner register \
--docker-postgres latest
--docker-postgres latest
```
```
With the command above, you create a Runner that uses [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses[postgres](https://hub.docker.com/r/_/postgres/) database.
With the command above, you create a Runner that uses the [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses a[postgres](https://hub.docker.com/r/_/postgres/) database.
To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password.
This document has not been updated recently and could be out of date. For the latest documentation, see the [GitLab CI/CD](../README.md) page and the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
# Test a Clojure application with GitLab CI/CD
# Test a Clojure application with GitLab CI/CD
This example will guide you how to run tests in your Clojure application.
This example will guide you how to run tests on your Clojure application.
You can checkout the example [source](https://gitlab.com/dzaporozhets/clojure-web-application) and check [CI status](https://gitlab.com/dzaporozhets/clojure-web-application/builds?scope=all).
You can view or fork the [example source](https://gitlab.com/dzaporozhets/clojure-web-application) and view the logs of its past [CI jobs](https://gitlab.com/dzaporozhets/clojure-web-application/builds?scope=finished).
## Configure the project
## Configure the project
...
@@ -28,8 +35,9 @@ test:
...
@@ -28,8 +35,9 @@ test:
-lein test
-lein test
```
```
In before script we install JRE and [Leiningen](http://leiningen.org/).
In `before_script`, we install JRE and [Leiningen](http://leiningen.org/).
Sample project uses [migratus](https://github.com/yogthos/migratus) library to manage database migrations.
So we added database migration as last step of `before_script` section
The sample project uses the [migratus](https://github.com/yogthos/migratus) library to manage database migrations, and
we have added a database migration as the last step of `before_script`.
You can use public runners available on `gitlab.com` for testing your application with such configuration.
You can use public runners available on `gitlab.com` for testing your application with this configuration.
