Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
5f6117c0
Commit
5f6117c0
authored
Nov 05, 2015
by
Job van der Voort
Committed by
Achilleas Pipinellis
Dec 01, 2015
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
update ci docs with yml reason and better quickstart
parent
13c6096e
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
156 additions
and
76 deletions
+156
-76
doc/ci/quick_start/README.md
doc/ci/quick_start/README.md
+139
-63
doc/ci/yaml/README.md
doc/ci/yaml/README.md
+17
-13
No files found.
doc/ci/quick_start/README.md
View file @
5f6117c0
# 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:
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.
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.
What is important is that each job is run independently from each other.
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.
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 complete
`.gitlab-ci.yml`
syntax, please check the
[
Configuring project (.gitlab-ci.yml)
](
../yaml/README.md
)
.
For more information and a complete
`.gitlab-ci.yml`
syntax, please check
[
the documentation on .gitlab-ci.yml
](
../yaml/README.md
)
.
##
5. Add file and push .gitlab-ci.yml to repository
##
# Push `.gitlab-ci.yml` to GitLab
Once you created
`.gitlab-ci.yml`
you should add it to git repository and push it 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.
You can also go to the
**Commits**
page and notice the little clock icon next
to the commit SHA.
![
New commit pending
](
img/new_commit.png
)
Clicking on the clock icon you will be directed to the builds page for that
specific commit.
![
Single commit builds page
](
img/single_commit_status_pending.png
)
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.
The next step is to configure a Runner so that it picks the pending jobs.
## 2. 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.
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_.
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
<https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>
.
In order to have a functional Runner you need to:
1.
[
Install it
][
runner-install
]
2.
[
Configure it
](
../runners/README.md#registering-a-specific-runner
)
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**
.
![
](
new_commit
.png
)
![
Activated runners
](
img/runners_activated
.png
)
However the commit has status
**pending**
which means that commit was not yet picked by runner.
### Shared Runners
## 6. Configure runner
If you use
[
GitLab.com
](
https://gitlab.com/
)
you can use
**Shared Runners**
provided by GitLab Inc.
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
.
These are special virtual machines that are run on GitLab's infrastructure that
can build any project
.
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
)
.
To enable
**Shared Runners**
you have to go to your project's
**Settings**
->
**Runners**
and click
**Enable shared runners**
.
To check if you have runners assigned to your project go to
**Runners**
. You will find there information how to setup project specific runner:
[
Read more on Shared Runners
](
../runners/README.md
)
.
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
## 3. Seeing the status of your build
If you do it correctly your runner should be shown under
**Runners activated for this project**
:
After configuring the Runner succesfully, you should see the status of your
last commit change from _pending_ to either _running_, _success_ or _failed_.
![](
runners_activated.png
)
You can view all builds, by going to the
**Builds**
page in your project.
### Shared runners
![
Commit status
](
img/builds_status.png
)
If you use
[
gitlab.com/ci
](
https://gitlab.com/ci/
)
you can use
**Shared runners**
provided by GitLab Inc
.
Th
ese 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
.
By clicking on a Build ID, you will be able to see the log of that build
.
Th
is is important to diagnose why a build failed or acted differently than
you expected
.
## 7. Check status of commit
![
Build log
](
img/build_log.png
)
If everything went OK and you go to commit, the status of the commit should change from
**pending**
to either
**running**
,
**success**
or
**failed**
.
You are also able to view the status of any commit in the various pages in
GitLab, such as
**Commits**
and
**Merge Requests**
.
![](
commit_status.png
)
## Next steps
You can click
**Build ID**
to view build log for specific job.
Awesome! You started using CI in GitLab!
## 8. Congratulations!
Next you can look into doing more with the CI. Many people are using GitLab
to package, containerize, test and deploy software.
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.
We have a number of
[
examples
](
../examples/README.md
)
available.
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.
[
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/
doc/ci/yaml/README.md
View file @
5f6117c0
...
...
@@ -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.
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment