Commit 3efd59b9 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs-ssot-review-ci-examples' into 'master'

Update CI Examples section to confirm to SSOT Documentation standards

Closes #61507

See merge request gitlab-org/gitlab-ce!29397
parents e0aabd52 3fe11b13
......@@ -127,12 +127,10 @@ Its feature set is listed on the table below according to DevOps stages.
## Examples
GitLab provides examples of configuring GitLab CI/CD in the form of:
Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms
on the [CI Examples](examples/README.md) page.
- A collection of [examples and other resources](examples/README.md).
- Example projects that are available at the [`gitlab-examples`](https://gitlab.com/gitlab-examples) group. For example, see:
- [`multi-project-pipelines`](https://gitlab.com/gitlab-examples/multi-project-pipelines) for examples of implementing multi-project pipelines.
- [`review-apps-nginx`](https://gitlab.com/gitlab-examples/review-apps-nginx/) provides an example of using Review Apps.
GitLab also provides [example projects](https://gitlab.com/gitlab-examples) pre-configured to use GitLab CI/CD.
## Administration **[CORE ONLY]**
......
This diff is collapsed.
......@@ -4,6 +4,7 @@ author: Fabio Busatto
author_gitlab: bikebilly
level: intermediate
article_type: tutorial
type: tutorial
date: 2017-08-15
---
......@@ -16,8 +17,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory
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-app`: the app using the previous one as a dependency (available at <https://gitlab.com/gitlab-examples/maven/simple-maven-app>)
- `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 (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 also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it.
......
# Browser Performance Testing with the Sitespeed.io container
---
type: howto
---
CAUTION: **Caution:**
# Browser Performance Testing with the sitespeed.io container
NOTE: **Note:**
The job definition shown below is supported on GitLab 11.5 and later versions.
It also requires the GitLab Runner 11.5 or later.
For earlier versions, use the [previous job definitions](#previous-job-definitions).
This example shows how to run the
[Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on
your code by using GitLab CI/CD and [Sitespeed.io](https://www.sitespeed.io)
[sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on
your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io)
using Docker-in-Docker.
First, you need GitLab Runner with
......@@ -38,20 +42,20 @@ performance:
```
The above example will create a `performance` job in your CI/CD pipeline and will run
Sitespeed.io against the webpage you defined in `URL` to gather key metrics.
sitespeed.io against the webpage you defined in `URL` to gather key metrics.
The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for
Sitespeed.io is downloaded in order to save the report as a
sitespeed.io is downloaded in order to save the report as a
[Performance report artifact](../yaml/README.md#artifactsreportsperformance-premium)
that you can later download and analyze.
Due to implementation limitations we always take the latest Performance artifact available.
The full HTML Sitespeed.io report will also be saved as an artifact, and if you have
The full HTML sitespeed.io report will also be saved as an artifact, and if you have
[GitLab Pages](../../user/project/pages/index.md) enabled, it can be viewed
directly in your browser.
For further customization options of Sitespeed.io, including the ability to
provide a list of URLs to test, please consult
[their documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/).
For further customization options for sitespeed.io, including the ability to
provide a list of URLs to test, please see the
[Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) documentation.
TIP: **Tip:**
For [GitLab Premium](https://about.gitlab.com/pricing/) users, key metrics are automatically
......@@ -73,7 +77,7 @@ set this up:
1. In the `performance` job, read the previous artifact into an environment
variable, like `$CI_ENVIRONMENT_URL`, and use it to parameterize the test
URLs.
1. You can now run the Sitespeed.io container against the desired hostname and
1. You can now run the sitespeed.io container against the desired hostname and
paths.
Your `.gitlab-ci.yml` file would look like:
......
---
type: reference, howto
---
# Analyze your project's Code Quality
CAUTION: **Caution:**
......
......@@ -3,6 +3,7 @@ author: Dylan Griffith
author_gitlab: DylanGriffith
level: intermediate
article_type: tutorial
type: tutorial
date: 2018-06-07
last_updated: 2019-04-08
description: "Continuous Deployment of a Spring Boot application to Cloud Foundry with GitLab CI/CD"
......@@ -26,13 +27,13 @@ using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring
## Requirements
_We assume you are familiar with Java, GitLab, Cloud Foundry, and GitLab CI/CD._
This tutorial assumes you are familiar with Java, GitLab, Cloud Foundry, and GitLab CI/CD.
To follow along with this tutorial you will need the following:
To follow along, you will need:
- An account on [Pivotal Web Services (PWS)](https://run.pivotal.io/) or any
other Cloud Foundry instance
- An account on GitLab
other Cloud Foundry (CF) instance.
- An account on GitLab.
NOTE: **Note:**
You will need to replace the `api.run.pivotal.io` URL in the all below
......
---
type: tutorial
---
# Using Dpl as deployment tool
[Dpl](https://github.com/travis-ci/dpl) (dee-pee-ell) is a deploy tool made for
[Dpl](https://github.com/travis-ci/dpl) (prouncounced like the letters D-P-L) is a deploy tool made for
continuous deployment that's developed and used by Travis CI, but can also be
used with GitLab CI.
>**Note:**
We recommend to use Dpl if you're deploying to any of these services:
<https://github.com/travis-ci/dpl#supported-providers>.
Dpl can be used to deploy to any of the [supported providers](https://github.com/travis-ci/dpl#supported-providers).
## Requirements
......@@ -50,8 +52,8 @@ To use different provider take a look at long list of [Supported Providers](http
## Using Dpl with Docker
When you use GitLab Runner you most likely configured it to use your server's shell commands.
This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner).
In most cases, you will have configured [GitLab Runner](https://docs.gitlab.com/runner/) to use your server's shell commands.
This means that all commands are run in the context of local user (e.g. gitlab_runner or gitlab_ci_multi_runner).
It also means that most probably in your Docker container you don't have the Ruby runtime installed.
You will have to install it:
......
---
type: tutorial
---
# 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
image: tetraweb/php
......@@ -46,9 +50,9 @@ To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitla
### 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
before_script:
......@@ -68,7 +72,7 @@ In order, this means that:
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:
......@@ -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. 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 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
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:
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
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;
- Instead of pushing it live, you can push it to WordPress official repo (with creating a SVN commit & stuff);
- 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, etc.).
- You could generate i18n text domains on the fly.
---
......
......@@ -3,6 +3,7 @@ author: Ryan Hall
author_gitlab: blitzgren
level: intermediate
article_type: tutorial
type: tutorial
date: 2018-03-07
last_updated: 2019-03-11
---
......@@ -14,7 +15,7 @@ platforms without the use of plugins like Adobe Flash. Furthermore, by using Git
single game developers, as well as game dev teams, can easily host browser-based games online.
In this tutorial, we'll focus on DevOps, as well as testing and hosting games with Continuous
Integration/Deployment methods. We assume you are familiar with GitLab, javascript,
Integration/Deployment methods using [GitLab CI/CD](../../README.md). We assume you are familiar with GitLab, JavaScript,
and the basics of game development.
## The game
......
......@@ -3,6 +3,7 @@ author: Vincent Tunru
author_gitlab: Vinnl
level: advanced
article_type: user guide
type: tutorial
date: 2019-02-18
description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.'
---
......@@ -22,7 +23,9 @@ However, looking at the freshly deployed code to check whether it still looks an
expected is repetitive manual work, which means it is a prime candidate for automation. This is
where automated [end-to-end testing](https://martinfowler.com/bliki/BroadStackTest.html) comes in:
having the computer run through a few simple scenarios that requires the proper functioning of all
layers of your application, from the frontend to the database. In this article, we will discuss how
layers of your application, from the frontend to the database.
In this article, we will discuss how
to write such end-to-end tests, and how to set up GitLab CI/CD to automatically run these tests
against your new code, on a branch-by-branch basis. For the scope of this article, we will walk you
through the process of setting up GitLab CI/CD for end-to-end testing Javascript-based applications
......
......@@ -4,6 +4,7 @@ author: Mehran Rasulian
author_gitlab: mehranrasulian
level: intermediate
article_type: tutorial
type: tutorial
date: 2017-08-31
last_updated: 2019-03-06
---
......
---
type: tutorial
---
# Testing PHP projects
This guide covers basic building instructions for PHP projects.
There are covered two cases: testing using the Docker executor and testing
Two testing scenarios are covered: using the Docker executor and
using the Shell executor.
## Test PHP projects using the Docker executor
......@@ -245,7 +249,7 @@ before_script:
...
```
## Access private packages / dependencies
## Access private packages or dependencies
If your test suite needs to access a private repository, you need to configure
[the SSH keys](../ssh_keys/README.md) in order to be able to clone it.
......@@ -254,7 +258,7 @@ If your test suite needs to access a private repository, you need to configure
Most of the time you will need a running database in order for your tests to
run. If you are using the Docker executor you can leverage Docker's ability to
link to other containers. In GitLab Runner lingo, this can be achieved by
link to other containers. With GitLab Runner, this can be achieved by
defining a `service`.
This functionality is covered in [the CI services](../services/README.md)
......@@ -279,7 +283,7 @@ We have set up an [Example PHP Project][php-example-repo] for your convenience
that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few
Want to hack on it? Simply fork it, commit, and push your changes. Within a few
moments the changes will be picked by a public runner and the job will begin.
[php-hub]: https://hub.docker.com/r/_/php/
......
---
type: tutorial
---
# 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.
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
......@@ -46,9 +50,9 @@ production:
This project has three jobs:
- `test` - used to test Django application,
- `staging` - used to automatically deploy staging environment every push to `master` branch
- `production` - used to automatically deploy production environment for every created tag
- `test` - used to test Django application.
- `staging` - used to automatically deploy staging environment every push to `master` branch.
- `production` - used to automatically deploy production environment for every created tag.
## Store API keys
......@@ -67,8 +71,9 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/).
## Create Runner
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).
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
gitlab-runner register \
......@@ -81,6 +86,6 @@ gitlab-runner register \
--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.
---
type: tutorial
---
# 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
......@@ -53,13 +57,14 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun
## Create 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
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/).
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
gitlab-runner register \
......@@ -72,6 +77,6 @@ gitlab-runner register \
--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.
---
type: tutorial
---
NOTE: **Note:**
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
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
......@@ -28,8 +35,9 @@ test:
- lein test
```
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
In `before_script`, we install JRE and [Leiningen](http://leiningen.org/).
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.
---
type: tutorial
---
# Test and deploy a Scala application to Heroku
This example demonstrates the integration of GitLab CI with Scala
applications using SBT. Checkout the example
[project](https://gitlab.com/gitlab-examples/scala-sbt) and
[build status](https://gitlab.com/gitlab-examples/scala-sbt/builds).
applications using SBT. You can view or fork the [example project](https://gitlab.com/gitlab-examples/scala-sbt)
and view the logs of its past [CI jobs](https://gitlab.com/gitlab-examples/scala-sbt/-/jobs?scope=finished).
## Add `.gitlab-ci.yml` file to project
......@@ -41,12 +44,14 @@ deploy:
- dpl --provider=heroku --app=gitlab-play-sample-app --api-key=$HEROKU_API_KEY
```
The `before_script` installs [SBT](http://www.scala-sbt.org/) and
displays the version that is being used. The `test` stage executes SBT
to compile and test the project.
[scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
In the above configuration:
- The `before_script` installs [SBT](http://www.scala-sbt.org/) and
displays the version that is being used.
- The `test` stage executes SBT to compile and test the project.
- [sbt-scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
plugin to measure test coverage.
The `deploy` stage automatically deploys the project to Heroku using dpl.
- The `deploy` stage automatically deploys the project to Heroku using dpl.
You can use other versions of Scala and SBT by defining them in
`build.sbt`.
......
......@@ -3,6 +3,7 @@ author: Alexandre S Hostert
author_gitlab: Hostert
level: beginner
article_type: tutorial
type: tutorial
date: 2018-02-20
last_updated: 2019-03-06
---
......@@ -16,11 +17,11 @@ simultaneous users.
That's why we're hearing so much about Phoenix today.
In this tutorial, we'll teach you how to set up GitLab CI/CD to build and test a Phoenix
In this tutorial, we'll teach you how to set up [GitLab CI/CD](../../README.md) to build and test a Phoenix
application.
_We assume that you know how to create a Phoenix app, run tests locally, and how to work with Git
and GitLab UI._
The tutorial assumes that you know how to create a Phoenix app, run tests locally, and how to work with Git
and the GitLab UI.
## Introduction
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment