update ci docs with yml reason and better quickstart
This commit is contained in:
parent
13c6096e42
commit
5f6117c0aa
2 changed files with 156 additions and 76 deletions
|
@ -1,44 +1,62 @@
|
|||
# Quick Start
|
||||
|
||||
To start building projects with GitLab CI a few steps needs to be done.
|
||||
GitLab Continuous Integration (CI) is fully integrated into GitLab itself. You
|
||||
only need to enable it in the Services settings of your project.
|
||||
|
||||
## 1. Install GitLab and CI
|
||||
This guide assumes that you:
|
||||
|
||||
First you need to have a working GitLab and GitLab CI instance.
|
||||
- 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
|
||||
|
||||
You can omit this step if you use [GitLab.com](https://GitLab.com/).
|
||||
In brief, the steps needed to have a working CI can be summed up to:
|
||||
|
||||
## 2. Create repository on GitLab
|
||||
1. Create a new project
|
||||
1. Add `.gitlab-ci.yml` to the git repository and push to GitLab
|
||||
1. Configure a Runner
|
||||
|
||||
Once you login on your GitLab add a new repository where you will store your source code.
|
||||
Push your application to that repository.
|
||||
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.
|
||||
|
||||
## 3. Add project to CI
|
||||
Now, let's break it down to pieces and work on solving the GitLab CI puzzle.
|
||||
|
||||
The next part is to login to GitLab CI.
|
||||
Point your browser to the URL you have set GitLab or use [gitlab.com/ci](https://gitlab.com/ci/).
|
||||
## 1. Creating a `.gitlab-ci.yml` file
|
||||
|
||||
On the first screen you will see a list of GitLab's projects that you have access to:
|
||||
**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.
|
||||
|
||||
![Projects](projects.png)
|
||||
For other methods read [how to enable the GitLab CI service](../enable_ci.md).
|
||||
|
||||
Click **Add Project to CI**.
|
||||
This will create project in CI and authorize GitLab CI to fetch sources from GitLab.
|
||||
### What is `.gitlab-ci.yml`
|
||||
|
||||
> GitLab CI creates unique token that is used to configure GitLab CI service in GitLab.
|
||||
> This token allows to access GitLab's repository and configures GitLab to trigger GitLab CI webhook on **Push events** and **Tag push events**.
|
||||
> You can see that token by going to Project's Settings > Services > GitLab CI.
|
||||
> You will see there token, the same token is assigned in GitLab CI settings of project.
|
||||
The `.gitlab-ci.yml` file is where you configure what CI does with your project.
|
||||
It lives in the root of your repository.
|
||||
|
||||
## 4. Create project's configuration - .gitlab-ci.yml
|
||||
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
|
||||
file and start builds on _Runners_ according to the contents of the file,
|
||||
for that commit.
|
||||
|
||||
The next: You have to define how your project will be built.
|
||||
GitLab CI uses [YAML](https://en.wikipedia.org/wiki/YAML) file to store build configuration.
|
||||
You need to create `.gitlab-ci.yml` in root directory of your repository:
|
||||
Because `.gitlab-ci.yml` is in the repository, it is version controlled,
|
||||
old versions still build succesfully, 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].
|
||||
|
||||
`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file.
|
||||
|
||||
### Creating a simple `.gitlab-ci.yml` file
|
||||
|
||||
You need to create a file named `.gitlab-ci.yml` in the root directory of your
|
||||
repository. Below is an example for a Ruby on Rails project.
|
||||
|
||||
```yaml
|
||||
before_script:
|
||||
- bundle install
|
||||
- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
|
||||
- ruby -v
|
||||
- which ruby
|
||||
- gem install bundler --no-ri --no-rdoc
|
||||
- bundle install --jobs $(nproc) "${FLAGS[@]}"
|
||||
|
||||
rspec:
|
||||
script:
|
||||
|
@ -49,71 +67,129 @@ rubocop:
|
|||
- bundle exec rubocop
|
||||
```
|
||||
|
||||
This is the simplest possible build configuration that will work for most Ruby applications:
|
||||
1. Define two jobs `rspec` and `rubocop` with two different commands to be executed.
|
||||
1. Before every job execute commands defined by `before_script`.
|
||||
This is the simplest possible build configuration that will work for most Ruby
|
||||
applications:
|
||||
|
||||
The `.gitlab-ci.yml` defines set of jobs with constrains how and when they should be run.
|
||||
The jobs are defined as top-level elements with name and always have to contain the `script`.
|
||||
Jobs are used to create builds, which are then picked by [runners](../runners/README.md) and executed within environment of the runner.
|
||||
What is important that each job is run independently from each other.
|
||||
1. Define two jobs `rspec` and `rubocop` with different commands to be executed.
|
||||
1. Before every job, the commands defined by `before_script` are executed.
|
||||
|
||||
For more information and complete `.gitlab-ci.yml` syntax, please check the [Configuring project (.gitlab-ci.yml)](../yaml/README.md).
|
||||
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.
|
||||
|
||||
## 5. Add file and push .gitlab-ci.yml to repository
|
||||
What is important is that each job is run independently from each other.
|
||||
|
||||
Once you created `.gitlab-ci.yml` you should add it to git repository and push it to GitLab.
|
||||
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.
|
||||
|
||||
For more information and a complete `.gitlab-ci.yml` syntax, please check
|
||||
[the documentation on .gitlab-ci.yml](../yaml/README.md).
|
||||
|
||||
### Push `.gitlab-ci.yml` to GitLab
|
||||
|
||||
Once you've created `.gitlab-ci.yml`, you should add it to your git repository
|
||||
and push it to GitLab.
|
||||
|
||||
```bash
|
||||
git add .gitlab-ci.yml
|
||||
git commit
|
||||
git commit -m "Add .gitlab-ci.yml"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
If you refresh the project's page on GitLab CI you will notice a one new commit:
|
||||
Now if you go to the **Builds** page you will see that the builds are pending.
|
||||
|
||||
![](new_commit.png)
|
||||
You can also go to the **Commits** page and notice the little clock icon next
|
||||
to the commit SHA.
|
||||
|
||||
However the commit has status **pending** which means that commit was not yet picked by runner.
|
||||
![New commit pending](img/new_commit.png)
|
||||
|
||||
## 6. Configure runner
|
||||
Clicking on the clock icon you will be directed to the builds page for that
|
||||
specific commit.
|
||||
|
||||
In GitLab CI, Runners run your builds.
|
||||
A runner is a machine (can be virtual, bare-metal or VPS) that picks up builds through the coordinator API of GitLab CI.
|
||||
![Single commit builds page](img/single_commit_status_pending.png)
|
||||
|
||||
A runner can be specific to a certain project or serve any project in GitLab CI.
|
||||
A runner that serves all projects is called a shared runner.
|
||||
More information about different runner types can be found in [Configuring runner](../runners/README.md).
|
||||
Notice that there are two jobs pending which are named after what we wrote in
|
||||
`.gitlab-ci.yml`. The red triangle indicates that there is no Runner configured
|
||||
yet for these builds.
|
||||
|
||||
To check if you have runners assigned to your project go to **Runners**. You will find there information how to setup project specific runner:
|
||||
The next step is to configure a Runner so that it picks the pending jobs.
|
||||
|
||||
1. Install GitLab Runner software. Checkout the [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner) section to install it.
|
||||
1. Specify following URL during runner setup: https://gitlab.com/ci/
|
||||
1. Use the following registration token during setup: TOKEN
|
||||
## 2. Configuring a Runner
|
||||
|
||||
If you do it correctly your runner should be shown under **Runners activated for this project**:
|
||||
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.
|
||||
|
||||
![](runners_activated.png)
|
||||
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_.
|
||||
|
||||
### Shared runners
|
||||
Find more information about different Runners in the
|
||||
[Runners](../runners/README.md) documentation.
|
||||
|
||||
If you use [gitlab.com/ci](https://gitlab.com/ci/) 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.
|
||||
To enable **Shared runners** you have to go to **Runners** and click **Enable shared runners** for this project.
|
||||
You can find whether any Runners are assigned to your project by going to
|
||||
**Settings** -> **Runners**.
|
||||
|
||||
## 7. Check status of commit
|
||||
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>.
|
||||
|
||||
If everything went OK and you go to commit, the status of the commit should change from **pending** to either **running**, **success** or **failed**.
|
||||
In order to have a functional Runner you need to:
|
||||
|
||||
![](commit_status.png)
|
||||
1. [Install it][runner-install]
|
||||
2. [Configure it](../runners/README.md#registering-a-specific-runner)
|
||||
|
||||
You can click **Build ID** to view build log for specific job.
|
||||
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).
|
||||
|
||||
## 8. Congratulations!
|
||||
Once the Runner has been set up, you should see it on the Runners page of your
|
||||
project, following **Settings** -> **Runners**.
|
||||
|
||||
You managed to build your first project using GitLab CI.
|
||||
You may need to tune your `.gitlab-ci.yml` file to implement build plan for your project.
|
||||
A few examples how it can be done you can find on [Examples](../examples/README.md) page.
|
||||
![Activated runners](img/runners_activated.png)
|
||||
|
||||
GitLab CI also offers **the Lint** tool to verify validity of your `.gitlab-ci.yml` which can be useful to troubleshoot potential problems.
|
||||
The Lint is available from project's settings or by adding `/lint` to GitLab CI url.
|
||||
### Shared 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.
|
||||
|
||||
To enable **Shared Runners** you have to go to your project's
|
||||
**Settings** -> **Runners** and click **Enable shared runners**.
|
||||
|
||||
[Read more on Shared Runners](../runners/README.md).
|
||||
|
||||
## 3. 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_.
|
||||
|
||||
You can view all builds, by going to the **Builds** page in your project.
|
||||
|
||||
![Commit status](img/builds_status.png)
|
||||
|
||||
By clicking on a Build ID, you will be able to see the log of that build.
|
||||
This is important to diagnose why a build failed or acted differently than
|
||||
you expected.
|
||||
|
||||
![Build log](img/build_log.png)
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
[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/
|
||||
|
|
|
@ -20,6 +20,22 @@ 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:
|
||||
|
||||
|
@ -185,7 +201,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 inclusive. If both `only` and `except` are defined in job specification the ref is filtered by `only` and `except`.
|
||||
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` 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.
|
||||
|
@ -198,18 +214,6 @@ 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.
|
||||
|
||||
|
|
Loading…
Reference in a new issue