diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2015-12-01 11:05:24 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2015-12-01 11:16:27 +0300 |
commit | 6805f1bc47640886020e5febf015a73e5862114c (patch) | |
tree | 33d214e6772b1467ae3788f81006ed71a47a6b93 /doc/ci | |
parent | aea5b72faafa6911377cb0c9fc0801269ac59e1e (diff) |
Clean up quick start quide [ci skip]
* Remove references to enabling CI since it it will be deprecated
* Revert changes in yaml/README.md, refine it in a separate MR
Diffstat (limited to 'doc/ci')
-rw-r--r-- | doc/ci/enable_ci.md | 39 | ||||
-rw-r--r-- | doc/ci/img/ci_service_disabled.png | bin | 3598 -> 0 bytes | |||
-rw-r--r-- | doc/ci/img/ci_service_enabled.png | bin | 3545 -> 0 bytes | |||
-rw-r--r-- | doc/ci/img/ci_service_mark_active.png | bin | 17193 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/README.md | 61 | ||||
-rw-r--r-- | doc/ci/quick_start/img/runners.png | bin | 123048 -> 0 bytes | |||
-rw-r--r-- | doc/ci/yaml/README.md | 30 |
7 files changed, 42 insertions, 88 deletions
diff --git a/doc/ci/enable_ci.md b/doc/ci/enable_ci.md deleted file mode 100644 index 01c684dabec..00000000000 --- a/doc/ci/enable_ci.md +++ /dev/null @@ -1,39 +0,0 @@ -# Enable GitLab CI - -GitLab Continuous Integration (CI) is fully integrated into GitLab itself as -of [version 8.0](https://about.gitlab.com/2015/09/22/gitlab-8-0-released/). - -First, head over your project's page that you would like to enable GitLab CI -for. If you can see the **Builds** tab in the sidebar, then GitLab CI is -already enabled and you can skip reading the rest of this guide. - -![Builds tab](img/builds_tab.png) - -If not, there are two ways to enable it in your project. - -## Use .gitlab-ci.yml to enable GitLab CI - -GitLab CI will be automatically enabled if you just push a -[`.gitlab-ci.yml`](yaml/README.md) in your git repository. GitLab will -pick up the change immediately and GitLab CI will be enabled for this project. -This is the recommended way. - -## Manually enable GitLab CI - -The second way is to manually enable it in the project's **Services** settings -and this is also the way to disable it if needed. - -Go to **Settings > Services** and search for **GitLab CI**. Its state should -be disabled. - -![CI service disabled](img/ci_service_disabled.png) - -Click on **GitLab CI** to enter its settings, mark it as active and hit -**Save**. - -![Mark CI service as active](img/ci_service_mark_active.png) - -Do you see that green dot? Then good, the service is now enabled! You can also -check its status under **Services**. - -![CI service enabled](img/ci_service_enabled.png) diff --git a/doc/ci/img/ci_service_disabled.png b/doc/ci/img/ci_service_disabled.png Binary files differdeleted file mode 100644 index 351de4267a4..00000000000 --- a/doc/ci/img/ci_service_disabled.png +++ /dev/null diff --git a/doc/ci/img/ci_service_enabled.png b/doc/ci/img/ci_service_enabled.png Binary files differdeleted file mode 100644 index dfe7488c1ba..00000000000 --- a/doc/ci/img/ci_service_enabled.png +++ /dev/null diff --git a/doc/ci/img/ci_service_mark_active.png b/doc/ci/img/ci_service_mark_active.png Binary files differdeleted file mode 100644 index 8bc8694cec3..00000000000 --- a/doc/ci/img/ci_service_mark_active.png +++ /dev/null diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 7771d78d91f..a9b36139de9 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -1,7 +1,7 @@ # Quick Start -GitLab Continuous Integration (CI) is fully integrated into GitLab itself. You -only need to enable it in the Services settings of your project. +Starting from version 8.0, GitLab Continuous Integration (CI) is fully +integrated into GitLab itself and is enabled by default on all projects. This guide assumes that you: @@ -21,17 +21,10 @@ automagically started by the Runner and will appear under the project's Now, let's break it down to pieces and work on solving the GitLab CI puzzle. -## 1. Creating a `.gitlab-ci.yml` file +## Creating a `.gitlab-ci.yml` file - **GitLab CI** service is enabled automatically on the first push of a - `.gitlab-ci.yml` file in your repository and this is the recommended way. - -For other methods read [how to enable the GitLab CI service](../enable_ci.md). - - **GitLab CI** service is enabled automatically on the first push of a - `.gitlab-ci.yml` file in your repository and this is the recommended way. - -For other methods read [how to enable the GitLab CI service](../enable_ci.md). +Before you create `.gitlab-ci.yml` let's first explain in brief what this is +all about. ### What is `.gitlab-ci.yml` @@ -48,7 +41,9 @@ 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]. -`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file. +**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 +tabs. ### Creating a simple `.gitlab-ci.yml` file @@ -75,20 +70,21 @@ rubocop: This is the simplest possible build configuration that will work for most Ruby applications: -1. Define two jobs `rspec` and `rubocop` with different commands to be executed. +1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with + different commands to be executed. 1. Before every job, the commands defined by `before_script` are executed. The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when -they should be run. The jobs are defined as top-level elements with a name and -always have to contain the `script` name. Jobs are used to create builds, -which are then picked by [Runners](../runners/README.md) and executed within -the environment of the Runner. +they should be run. The jobs are defined as top-level elements with a name (in +our case `rspec` and `rubocop`) and always have to contain the `script` keyword. +Jobs are used to create builds, which are then picked by +[Runners](../runners/README.md) and executed within the environment of the Runner. What is important is that each job is run independently from each other. If you want to check whether your `.gitlab-ci.yml` file is valid, there is a Lint tool under the page `/ci/lint` of your GitLab instance. You can also find -the link under **Settings** -> **CI settings** in your project. +the link under **Settings > CI settings** in your project. For more information and a complete `.gitlab-ci.yml` syntax, please check [the documentation on .gitlab-ci.yml](../yaml/README.md). @@ -122,13 +118,13 @@ yet for these builds. The next step is to configure a Runner so that it picks the pending jobs. -## 2. Configuring a Runner +## Configuring a Runner 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 have Internet access. +Runner is configured to has 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_. @@ -137,22 +133,23 @@ Find more information about different Runners in the [Runners](../runners/README.md) documentation. You can find whether any Runners are assigned to your project by going to -**Settings** -> **Runners**. -Setting up a Runner is easy and straightforward. The official Runner supported - -by GitLab is written in Go and can be found at +**Settings > Runners**. Setting up a Runner is easy and straightforward. The +official Runner supported by GitLab is written in Go and can be found at <https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>. -In order to have a functional Runner you need to: +In order to have a functional Runner you need to follow two steps: 1. [Install it][runner-install] 2. [Configure it](../runners/README.md#registering-a-specific-runner) +Follow the links above to set up your own Runner or use a Shared Runner as +described in the next section. + For other types of unofficial Runners written in other languages, see the [instructions for the various GitLab Runners](https://about.gitlab.com/gitlab-ci/#gitlab-runner). Once the Runner has been set up, you should see it on the Runners page of your -project, following **Settings** -> **Runners**. +project, following **Settings > Runners**. ![Activated runners](img/runners_activated.png) @@ -161,15 +158,15 @@ project, following **Settings** -> **Runners**. If you use [GitLab.com](https://gitlab.com/) you can use **Shared Runners** provided by GitLab Inc. -These are special virtual machines that are run on GitLab's infrastructure that -can build any project. +These are special virtual machines that run on GitLab's infrastructure and can +build any project. To enable **Shared Runners** you have to go to your project's -**Settings** -> **Runners** and click **Enable shared runners**. +**Settings > Runners** and click **Enable shared runners**. [Read more on Shared Runners](../runners/README.md). -## 3. Seeing the status of your build +## Seeing the status of your build After configuring the Runner succesfully, you should see the status of your last commit change from _pending_ to either _running_, _success_ or _failed_. @@ -194,7 +191,7 @@ 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. -We have a number of [examples](../examples/README.md) available. +Visit our various languages examples at <https://gitlab.com/groups/gitlab-examples>. [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/ diff --git a/doc/ci/quick_start/img/runners.png b/doc/ci/quick_start/img/runners.png Binary files differdeleted file mode 100644 index 25b4046bc00..00000000000 --- a/doc/ci/quick_start/img/runners.png +++ /dev/null diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 9ee26c41e6d..3dbf1afc7a9 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -20,22 +20,6 @@ Of course a command can execute code directly (`./configure;make;make install`) Jobs are used to create builds, which are then picked up by [runners](../runners/README.md) and executed within the environment of the runner. What is important, is that each job is run independently from each other. -## Why `.gitlab-ci.yml` - -By placing a single configuration file in the root of your repository, -it is version controlled and you get all the advantages of git. - -In addition, builds for older versions of the repository will work just fine, -as GitLab look at the `.gitlab-ci.yml` of the pushed commit. -This means that forks also build without any problem. - -You can even set up different builds for different branches. This allows you -to only deploy the `production` branch, for instance. - -By having a single source of truth, everyone can view and contribute to the -stability of your CI builds, eventually improving the quality of your development -cycle. - ## .gitlab-ci.yml The YAML syntax allows for using more complex job specifications than in the above example: @@ -201,7 +185,7 @@ This are two parameters that allow for setting a refs policy to limit when jobs There are a few rules that apply to usage of refs policy: -1. `only` and `except` are exclusive. If both `only` and `except` are defined in job specification only `only` is taken into account. +1. `only` and `except` are inclusive. If both `only` and `except` are defined in job specification the ref is filtered by `only` and `except`. 1. `only` and `except` allow for using the regexp expressions. 1. `only` and `except` allow for using special keywords: `branches` and `tags`. These names can be used for example to exclude all tags and all branches. @@ -214,6 +198,18 @@ job: - branches # use special keyword ``` +1. `only` and `except` allow for specify repository path to filter jobs for forks. +The repository path can be used to have jobs executed only for parent repository. + +```yaml +job: + only: + - branches@gitlab-org/gitlab-ce + except: + - master@gitlab-org/gitlab-ce +``` +The above will run `job` for all branches on `gitlab-org/gitlab-ce`, except master . + ### tags `tags` is used to select specific runners from the list of all runners that are allowed to run this project. |