diff options
Diffstat (limited to 'doc/ci/quick_start/README.md')
| -rw-r--r-- | doc/ci/quick_start/README.md | 81 |
1 files changed, 62 insertions, 19 deletions
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index a9b36139de9..9aba4326e11 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -1,25 +1,47 @@ # Quick Start -Starting from version 8.0, GitLab Continuous Integration (CI) is fully -integrated into GitLab itself and is enabled by default on all projects. +>**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI) +is fully integrated into GitLab itself and is [enabled] by default on all +projects. -This guide assumes that you: +The TL;DR version of how GitLab CI works is the following. -- have a working GitLab instance of version 8.0 or higher or are using - [GitLab.com](https://gitlab.com/users/sign_in) -- have a project in GitLab that you would like to use CI for +--- + +GitLab offers a [continuous integration][ci] service. If you +[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, +and configure your GitLab project to use a [Runner], then each merge request or +push triggers a build. + +The `.gitlab-ci.yml` file tells the GitLab runner what do to. By default it +runs three [stages]: `build`, `test`, and `deploy`. -In brief, the steps needed to have a working CI can be summed up to: +If everything runs OK (no non-zero return values), you'll get a nice green +checkmark associated with the pushed commit or merge request. This makes it +easy to see whether a merge request will cause any of the tests to fail before +you even look at the code. -1. Create a new project -1. Add `.gitlab-ci.yml` to the git repository and push to GitLab +Most projects only use GitLab's CI service to run the test suite so that +developers get immediate feedback if they broke something. + +So in brief, the steps needed to have a working CI can be summed up to: + +1. Add `.gitlab-ci.yml` to the root directory of your repository 1. Configure a Runner -From there on, on every push to your git repository the build will be +From there on, on every push to your Git repository, the build will be automagically started by the Runner and will appear under the project's `/builds` page. -Now, let's break it down to pieces and work on solving the GitLab CI puzzle. +--- + +This guide assumes that you: + +- have a working GitLab instance of version 8.0 or higher or are using + [GitLab.com](https://gitlab.com/users/sign_in) +- have a project in GitLab that you would like to use CI for + +Let's break it down to pieces and work on solving the GitLab CI puzzle. ## Creating a `.gitlab-ci.yml` file @@ -36,13 +58,13 @@ file and start builds on _Runners_ according to the contents of the file, for that commit. Because `.gitlab-ci.yml` is in the repository, it is version controlled, -old versions still build succesfully, forks can easily make use of CI, +old versions still build successfully, forks can easily make use of CI, branches can have separate builds and you have a single source of truth for CI. You can read more about the reasons why we are using `.gitlab-ci.yml` [in our blog about it][blog-ci]. **Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file -so you have to pay extra attention to the identation. Always use spaces, not +so you have to pay extra attention to the indentation. Always use spaces, not tabs. ### Creating a simple `.gitlab-ci.yml` file @@ -124,7 +146,7 @@ In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`. A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers. GitLab and the Runners communicate through an API, so the only needed requirement is that the machine on which the -Runner is configured to has Internet access. +Runner is configured to have Internet access. A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects it's called a _Shared Runner_. @@ -168,7 +190,7 @@ To enable **Shared Runners** you have to go to your project's ## Seeing the status of your build -After configuring the Runner succesfully, you should see the status of your +After configuring the Runner successfully, you should see the status of your last commit change from _pending_ to either _running_, _success_ or _failed_. You can view all builds, by going to the **Builds** page in your project. @@ -184,14 +206,35 @@ you expected. You are also able to view the status of any commit in the various pages in GitLab, such as **Commits** and **Merge Requests**. -## Next steps +## Enabling build emails + +If you want to receive e-mail notifications about the result status of the +builds, you should explicitly enable the **Builds Emails** service under your +project's settings. + +For more information read the [Builds emails service documentation] +(../../project_services/builds_emails.md). + +## Builds badge + +You can access a builds badge image using following link: + +``` +http://example.gitlab.com/namespace/project/badges/branch/build.svg +``` Awesome! You started using CI in GitLab! -Next you can look into doing more with the CI. Many people are using GitLab -to package, containerize, test and deploy software. +## Examples -Visit our various languages examples at <https://gitlab.com/groups/gitlab-examples>. +Visit the [examples README][examples] to see a list of examples using GitLab +CI with various languages. [runner-install]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tree/master#installation [blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ +[examples]: ../examples/README.md +[ci]: https://about.gitlab.com/gitlab-ci/ +[yaml]: ../yaml/README.md +[runner]: ../runners/README.md +[enabled]: ../enable_or_disable_ci.md +[stages]: ../yaml/README.md#stages |