documentation for gitlab-ci.yml

3 files changed, 82 insertions, 2 deletions

diff --git a/app/views/shared/_guide.html.haml b/app/views/shared/_guide.html.haml
index 7a5117f..d34a1be 100644
--- a/app/views/shared/_guide.html.haml
+++ b/app/views/shared/_guide.html.haml
@@ -6,8 +6,7 @@
       Add at least one runner to the project.
       Go to #{link_to 'Runners page', project_runners_path(@project), target: :blank} for instructions.
     %li
-      Setup at least one Job with a build script.
-      Go to 'Jobs page' target: :blank for instructions.
+      Put the .gitlab-ci.yml to the root of your repository. Examples can be found in #{link_to "Configuraton of your builds with .gitlab-ci.yaml", "http://doc.gitlab.com/ci/builds_configuration/README.html", target: :blank}
     %li
       Visit #{link_to 'GitLab project settings', @project.gitlab_url + "/services/gitlab_ci/edit", target: :blank}
       and press the "Test settings" button.
diff --git a/doc/README.md b/doc/README.md
index 948b146..8307276 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -5,6 +5,7 @@
 + [Install](install/installation.md)
 + [Update](update/README.md)
 + [Runners](runners/README.md)
++ [Builds Configuration](builds_configuration/README.md)
 + [Permissions](permissions/README.md) User permissions
 + [Rake Tasks](raketasks/README.md) Backup and restore take tasks
 + [Migrating to packaged CI](migration_to_omnibus/README.md)
diff --git a/doc/builds_configuration/README.md b/doc/builds_configuration/README.md
new file mode 100644
index 0000000..08841d9
--- /dev/null
+++ b/doc/builds_configuration/README.md
@@ -0,0 +1,80 @@
+## Configuraton of your builds with .gitlab-ci.yaml
+
+Sinse 7.12 version GitLab CI uses special yaml file for configuration your builds. This yaml file should be placed in the root of your repository and should be named as .gitlab-ci.yml. This file contains 4 main sections: skep_refs, before_script, jobs and deploy_jobs. Example of configuration file:
+
+```
+skip_refs: staging
+before_script: |
+  export PATH=$HOME/bin:/usr/local/bin:/usr/bin:/bin
+  gem install bundler
+  cp config/database.yml.mysql config/database.yml
+  bundle install --without postgres production --jobs $(nproc)
+  bundle exec rake db:create RAILS_ENV=test
+jobs:
+- script: "bundle exec rspec"
+  name: Rspec
+  runner: mysql,ruby
+- "bundle exec cucumber" # or even so
+deploy_jobs:
+- "bundle exec cap deploy"
+
+```
+
+Let's have a close look at each section.
+
+### skip_refs
+This parameter defines ref or list of refs to skip. You can use glob pattern syntax as well. Example: "staging,feature-*"
+
+### jobs
+Here you can specify parameters of your builds. There are serveral ways you can configure it. Using hash:
+```
+jobs:
+- script: "bundle exec rspec" # (required) - commands to run
+  name: Rspec                 # (optional) - name of build
+  runner: mysql,ruby          # (optional) - runner tags, only runners which have these tags will be used
+  branches: true              # (optional) - make builds for regular branches
+  tags: true                  # (optional) - make builds for tags
+```
+`script` can also cantain several commands using YAML multiline string:
+```
+- script: |
+    bundle updata
+    bundle exec rspec
+```
+you can also fill commands like array:
+```
+- script:
+  - bundle update
+  - bundle exec rspec
+```
+And there is one more way to specify build configuration, using string:
+```
+jobs:
+- bundle exec rspec
+```
+In this way, name of build will be taken from this command line.
+
+## deploy_jobs
+Deploy Jobs define the builds that will be run when all job succedded. Define using hash:
+
+```
+deploy_jobs:
+- script: |                             # (required) - command
+    bundle update
+    bundle exec cap deploy
+  name: Deploy                          # (optional) - name
+  refs: deploy                          # (optional) - run only when the above git refs strings match the branch or tag that was pushed.
+  runner: ruby,deploy                   # (optional) - runner tags, only runners which have these tags will be used
+```
+
+`script` can be a multiline script or array like for regular jobs.
+
+You can also define deploy jobs with string:
+
+```
+deploy_jobs:
+-  "bundle exec cap deploy"
+```
+
+## before_script
+This section is used for defining command that should be run before all builds, including deploy builds. Can be an array or multiline string.
\ No newline at end of file