Reorganize CI examples, add more links

2 files changed, 143 insertions, 46 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 66f8a892a7d..b3780a08828 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -1,76 +1,112 @@
-# GitLab Continuous Integration
+# GitLab Continuous Integration (GitLab CI)
 
 ![CI/CD pipeline graph](img/cicd_pipeline_infograph.png)
 
 The benefits of Continuous Integration are huge when automation plays an
-integral part of your workflow. GitLab comes with integrated Continuous
-Integration (CI) and Continuous Delivery (CD) to test, build and deploy your
-code.
+integral part of your workflow. GitLab comes with built-in Continuous
+Integration, Continuous Deployment, and Continuous Delivery support to build,
+test, and deploy your application.
 
 Here's some info we've gathered to get you started.
 
 ## Getting started
 
+The first steps towards your GitLab CI journey.
+
 - [Getting started with GitLab CI](quick_start/README.md)
-- [Configure a Runner, the application that runs your jobs](runners/README.md)
 - [Pipelines and jobs](pipelines.md)
-- [Environments and deployments](environments.md)
-- [Job artifacts](../user/project/pipelines/job_artifacts.md)
-- **Using Docker**
-  - [Use Docker images with GitLab Runner](docker/using_docker_images.md)
-  - [Use CI to build Docker images](docker/using_docker_build.md)
-  - [CI services (linked Docker containers)](services/README.md)
-- **Blog posts**
-  - [Getting started with GitLab and GitLab CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/)
-  - [GitLab CI: Run jobs sequentially, in parallel or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/)
-  - [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/)
-  - [CI deployments and environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
-- **Videos**
-  - [Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/)
+- [Configure a Runner, the application that runs your jobs](runners/README.md)
+- **Articles:**
+  - [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/)
+  - [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/)
+  - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/)
+  - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/)
+  - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
+- **Videos:**
+  - [Demo (March, 2017): how to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/)
+  - [Webcast (April, 2016): getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/)
+- **Third-party videos:**
+  - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s)
+  - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8)
 
 ## Reference guides
 
 Once you get familiar with the getting started guides, you'll find yourself
 digging into specific reference guides.
 
-- [`.gitlab-ci.yml` reference](yaml/README.md)
-- **The permissions model**
-  - [User permissions](../user/permissions.md#gitlab-ci)
-  - [Jobs permissions](../user/permissions.md#jobs-permissions)
+- [`.gitlab-ci.yml` reference](yaml/README.md) - Learn all about the ins and
+  outs of `.gitlab-ci.yml` definitions
 - [CI Variables](variables/README.md) - Learn how to use variables defined in
   your `.gitlab-ci.yml` or secured ones defined in your project's settings
+- **The permissions model** - Learn about the access levels a user can have for
+  performing certain CI actions
+  - [User permissions](../user/permissions.md#gitlab-ci)
+  - [Jobs permissions](../user/permissions.md#jobs-permissions)
+
+## GitLab CI + Docker
+
+Leverage the power of Docker to run your CI pipelines.
+
+- [Use Docker images with GitLab Runner](docker/using_docker_images.md)
+- [Use CI to build Docker images](docker/using_docker_build.md)
+- [CI services (linked Docker containers)](services/README.md)
+- **Articles:**
+  - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/)
 
 ## Advanced use
 
-- [Git submodules](git_submodules.md)
-- [Review Apps](review_apps/index.md)
+Once you get familiar with the basics of GitLab CI, it's time to dive in and
+learn how to leverage its potential even more.
+
+- [Environments and deployments](environments.md) - Separate your jobs into
+  environments and use them for different purposes like testing, building and
+  deploying
+- [Job artifacts](../user/project/pipelines/job_artifacts.md)
+- [Git submodules](git_submodules.md) - How to run your CI jobs when Git
+  submodules are involved
 - [Auto deploy](autodeploy/index.md)
 - [Use SSH keys in your build environment](ssh_keys/README.md)
 - [Trigger jobs through the GitLab API](triggers/README.md)
-- [Using GitLab CI with GitLab Pages](../user/project/pages/index.md)
 
-## Special project configuration
+## Review Apps
+
+- [Review Apps](review_apps/index.md)
+- **Articles:**
+  - [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/)
+  - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
+
+## GitLab CI for GitLab Pages
+
+See the topic on [GitLab Pages](../user/project/pages/index.md).
 
-- [CI/CD pipelines settings](../user/project/pipelines/settings.md)
-- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
+## Special configuration
+
+You can change the default behavior of GitLab CI in your whole GitLab instance
+as well as in each project.
+
+- **Project specific**
+  - [CI/CD pipelines settings](../user/project/pipelines/settings.md)
+  - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
+- **Affecting the whole GitLab instance**
+  - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md)
 
 ## Examples
 
 >**Note:**
 A collection of `.gitlab-ci.yml` files is maintained at the
 [GitLab CI Yml project][gitlab-ci-templates].
-If your favorite programming language or framework are missing we would love
+If your favorite programming language or framework is missing we would love
 your help by sending a merge request with a `.gitlab-ci.yml`.
 
-Here is an collection of tutorials and guides on setting up your CI pipeline:
+Here is an collection of tutorials and guides on setting up your CI pipeline.
 
-- **Languages and frameworks**
-  - [Testing a PHP application](examples/php.md)
-  - [Test and deploy a Ruby application to Heroku](examples/test-and-deploy-ruby-application-to-heroku.md)
-  - [Test and deploy a Python application to Heroku](examples/test-and-deploy-python-application-to-heroku.md)
-  - [Test a Clojure application](examples/test-clojure-application.md)
-  - [Test a Scala application](examples/test-scala-application.md)
-  - [Test a Phoenix application](examples/test-phoenix-application.md)
+- [GitLab CI examples](examples/README.md) for the following languages and frameworks:
+  - [PHP](examples/php.md)
+  - [Ruby](examples/test-and-deploy-ruby-application-to-heroku.md)
+  - [Python](examples/test-and-deploy-python-application-to-heroku.md)
+  - [Clojure](examples/test-clojure-application.md)
+  - [Scala](examples/test-scala-application.md)
+  - [Phoenix](examples/test-phoenix-application.md)
   - [Run PHP Composer & NPM scripts then deploy them to a staging server](examples/deployment/composer-npm-deploy.md)
 - **Blog posts**
   - [Automated Debian packaging](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/)
@@ -87,6 +123,19 @@ Here is an collection of tutorials and guides on setting up your CI pipeline:
   - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
   - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
 
+## Integrations
+
+- **Articles:**
+  - [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/)
+  - [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/)
+  - [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/)
+
+## Why GitLab CI?
+
+- **Articles:**
+  - [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/)
+  - [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/)
+
 ## Breaking changes
 
 - [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index 5377bf9ee80..76c29b4618a 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -1,4 +1,4 @@
-# CI Examples
+# GitLab CI Examples
 
 A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates].
 If your favorite programming language or framework are missing we would love your help by sending a merge request
@@ -6,22 +6,70 @@ with a `.gitlab-ci.yml`.
 
 Apart from those, here is an collection of tutorials and guides on setting up your CI pipeline:
 
+## Languages, frameworks, OSs
+
+### PHP
+
 - [Testing a PHP application](php.md)
+- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md)
+
+### Ruby
+
 - [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md)
+
+### Python
+
 - [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md)
-- [Test a Clojure application](test-clojure-application.md)
+
+### Java
+
 - [Test a Scala application](test-scala-application.md)
+- **Articles:**
+  - [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/)
+
+### Clojure
+
+- [Test a Clojure application](test-clojure-application.md)
+
+### Elixir
+
 - [Test a Phoenix application](test-phoenix-application.md)
-- [Using `dpl` as deployment tool](deployment/README.md)
-- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/)
-- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md)
-- Help your favorite programming language and GitLab by sending a merge request
-  with a guide for that language.
+- **Articles:**
+  - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/)
+
+### iOS
+
+- **Articles:**
+  - [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+
+### Android
+
+- **Articles:**
+  - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/)
 
-## Outside the documentation
+### Other
 
-- [Blog post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/)
+- [Using `dpl` as deployment tool](deployment/README.md)
 - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples)
 - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
+- **Articles:**
+  - [Continuous Deployment with GitLab: how to build and deploy a Debian Package with GitLab CI](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/)
+
+## GitLab CI for GitLab Pages
+
+- [Example projects](https://gitlab.com/pages)
+- **Articles:**
+  - [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](../../project/pages/getting_started_part_four.html)
+  - [SSGs Part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/):
+  examples for Ruby-, NodeJS-, Python-, and GoLang-based SSGs
+  - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
+  - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/)
+
+See the topic [GitLab Pages](../../user/project/pages/index.html) for a complete overview.
+
+## More
+
+Help your favorite programming language and GitLab by sending a merge request
+with a guide for that language.
 
 [gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml