Merge branch 'master' into emma-xcode-833

Author: emdantrim

.gitignore

@@ -8,3 +8,5 @@ source/tmp/*
 tmp/
 .jekyll-metadata
 node_modules
+generated-language-mapping.json
+_data/trusty_mapping_data.yml

.travis.yml

@@ -6,7 +6,7 @@ python:
   - "3.5.2"
 branches:
   only:
-  - gh-pages
+  - master
 env:
   global:
     - PATH=$HOME/.local/user/bin:$PATH
@@ -18,23 +18,22 @@ cache:
 deploy:
   provider: heroku
   api_key:
-    secure: fkfayYzRdc0uh9iZeQKzC5/J3cKhVnyrkLRYSJmhixWtBHt87g7yzR1kGgsOce7OjqZ42bRn5W/gxyaDIUa+UMrt7RgURPASLy3rpm5wkk3iK2csvJaCixKcodI8UTXn7kRjYkrpQYcfvO1/25AnKBQKveobxSSAN3BQ3hERe5E=
+    secure: "hylw2GIHMvZKOKX3uPSaLEzVrUGEA9mzGEA0s4zK37W9HJCTnvAcmgRCwOkRuC4L7R4Zshdh/CGORNnBBgh1xx5JGYwkdnqtjHuUQmWEXCusrIURu/iEBNSsZZEPK7zBuwqMHj2yRm64JfbTDJsku3xdoA5Z8XJG5AMJGKLFgUQ="
   app: docs-travis-ci-com
+  skip_cleanup: true
   on:
-    branch: gh-pages
+    branch:
+    - master
 notifications:
   slack:
     rooms:
       secure: LPNgf0Ra6Vu6I7XuK7tcnyFWJg+becx1RfAR35feWK81sru8TyuldQIt7uAKMA8tqFTP8j1Af7iz7UDokbCCfDNCX1GxdAWgXs+UKpwhO89nsidHAsCkW2lWSEM0E3xtOJDyNFoauiHxBKGKUsApJTnf39H+EW9tWrqN5W2sZg8=
     on_success: never
+  webhooks:
+    https://docs.travis-ci.com/update_webhook_payload_doc
 install:
   - bundle install --deployment
-  - pip install --upgrade pip
-  - pip install coala-bears
-  - npm install remark-cli@2
-  - npm install -g alex
 before_script:
   - rvm use 2.3.1 --install
 script:
   - bundle exec rake test
-  - coala --non-interactive Language

Gemfile

@@ -12,6 +12,8 @@ gem 'rack-jekyll'
 gem 'rack-ssl-enforcer'
 gem 'puma'
 
+gem 'faraday'
+
 gem 'rake'
 
 gem 'html-proofer', '~> 3.0'

Gemfile.lock

@@ -13,6 +13,8 @@ GEM
     concurrent-ruby (1.0.5)
     ethon (0.10.1)
       ffi (>= 1.3.0)
+    faraday (0.12.0.1)
+      multipart-post (>= 1.2, < 3)
     ffi (1.9.18)
     forwardable-extended (2.6.0)
     html-proofer (3.6.0)
@@ -51,6 +53,7 @@ GEM
     mercenary (0.3.6)
     mini_portile2 (2.1.0)
     minitest (5.10.1)
+    multipart-post (2.0.0)
     nokogiri (1.7.1)
       mini_portile2 (~> 2.1.0)
     parallel (1.11.1)
@@ -83,6 +86,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  faraday
   html-proofer (~> 3.0)
   jekyll (>= 3.1.6)
   jekyll-paginate
@@ -94,4 +98,4 @@ DEPENDENCIES
   rdiscount (>= 2.2.0.1)
 
 BUNDLED WITH
-   1.13.6
+   1.14.6

README.md

@@ -1,4 +1,4 @@
-# About this repository [![Build Status](https://travis-ci.org/travis-ci/docs-travis-ci-com.svg?branch=gh-pages)](https://travis-ci.org/travis-ci/docs-travis-ci-com)
+# About this repository [![Build Status](https://travis-ci.org/travis-ci/docs-travis-ci-com.svg?branch=master)](https://travis-ci.org/travis-ci/docs-travis-ci-com)
 
 This is the documentation site for Travis CI! (<http://docs.travis-ci.com/>)
 
@@ -7,40 +7,63 @@ This is the documentation site for Travis CI! (<http://docs.travis-ci.com/>)
 Fork the repository, read the rest of this README file and make some changes.
 Once you're done with your changes send a pull request. Thanks!
 
-## How to edit the site
+## How to check your edit before sending PR
 
-Make sure you have Ruby and RubyGems installed. Next install
-[bundler](http://bundler.io/):
+You can inspect how your edits will be reflected by the documentation site.
 
-```bash
-gem install bundler
-```
+### Install dependencies
 
-Then install dependencies:
+1. Make sure you have Ruby and RubyGems installed.
 
-```bash
-bundle install --binstubs
-```
+1. Install [bundler](http://bundler.io/):
 
-In order to run a local Web server that will serve documentation site, run:
+    ```sh-session
+    $ gem install bundler
+    ```
 
-```bash
-./bin/jekyll serve
-```
+1. Install application dependencies:
+
+    ```sh-session
+    $ bundle install --binstubs
+    ```
 
-and then open [localhost:4000](http://localhost:4000/) in your browser.
+### Generate documentation
 
-To regenerate the HTML pages automatically when you make changes to Markdown source files, use
+Run
 
-```bash
-./bin/jekyll serve --watch
+```sh-session
+$ ./bin/jekyll build
 ```
 
-Note that quoted entities may be escaped or unescaped depending on the Ruby
-version (1.8 vs. 1.9) used. It is normal.
+
+### Run application server
+
+You are now ready to start your documentation site, using Jekyll or Puma.
+For documentation edits, Jekyll is sufficient.
+
+#### Starting and inspecting edits with Jekyll
+
+1. Run Jekyll server:
+
+    ```sh-session
+    $ ./bin/jekyll serve
+    ```
+
+1. Open [localhost:4000](http://localhost:4000/) in your browser.
+
+#### Starting and inspecting edits with Puma
+
+For more programmatical PRs (such as handling webhooks notification
+via POST), Puma is necessary.
+
+1. Run Puma server:
+
+    ```sh-session
+    $ ./bin/puma
+    ```
+
+1. Open [localhost:9292](http://localhost:9292/) in your browser.
 
 ## License
 
 Distributed under the [MIT license](https://opensource.org/licenses/MIT); the same as other Travis CI projects.
-
-***

Rakefile

@@ -10,7 +10,7 @@ task :test => :build do
 end
 
 desc 'Builds the site'
-task :build => :remove_output_dir do
+task :build => [:remove_output_dir, :gen_trusty_image_data] do
   FileUtils.rm '.jekyll-metadata' if File.exist?('.jekyll-metadata')
   sh 'bundle exec jekyll build --config=_config.yml'
 end
@@ -54,6 +54,23 @@ task :run_html_proofer do
   tester.run
 end
 
+desc 'Populate Trusty image table data'
+task :gen_trusty_image_data do
+  GENERATED_LANGUAGE_MAP_JSON_FILE = 'https://raw.githubusercontent.com/travis-infrastructure/terraform-config/master/aws-production-2/generated-language-mapping.json'
+
+  `curl -OsSfL '#{GENERATED_LANGUAGE_MAP_JSON_FILE}'`
+
+  json_data = JSON.load(File.read(File.basename(GENERATED_LANGUAGE_MAP_JSON_FILE)))
+  yaml_data = json_data.to_yaml
+
+  File.write(File.join(File.dirname(__FILE__), '_data', 'trusty_mapping_data.yml'), yaml_data)
+end
+
+desc 'Start Jekyll server'
+task :serve => [:gen_trusty_image_data] do
+  sh "bundle exec jekyll serve --config=_config.yml"
+end
+
 namespace :assets do
   task :precompile do
     puts `bundle exec jekyll build`

_config.yml

@@ -2,7 +2,7 @@ title: "Travis CI Documentation"
 email: "[email protected]"
 url: "https://docs.travis-ci.com"
 docs_github: "https://github.com/travis-ci/docs-travis-ci-com/"
-exclude: [bin, CNAME, Gemfile, Gemfile.lock, README.md, slate, vendor]
+exclude: [bin, CNAME, Gemfile, Gemfile.lock, README.md, slate, vendor, '*.erb']
 markdown: kramdown
 permalink: :title
 syntax-highlighting:

_includes/sidebar.html

@@ -34,6 +34,7 @@ <h3>Getting Started</h3>
         <li><a href="/user/customizing-the-build/">Customizing Your Build</a></li>
         <li><a href="/user/common-build-problems/">Common Build Problems</a></li>
         <li><a href="/user/speeding-up-the-build/">Speeding up the Build</a></li>
+        <li><a href="/user/build-stages/">Build Stages (beta)</a></li>
         <li><a href="/user/docker/">Using Docker in your Build</a></li>
         <li><a href="/user/gui-and-headless-browsers/">Headless Testing with Browsers</a></li>
         <li><a href="/user/pull-requests/">Building Pull Requests</a></li>
@@ -72,7 +73,7 @@ <h3>Deployments and Uploads</h3>
       <h3>CI Environment Reference</h3>
       <ul>
       <li><a href="/user/ci-environment/">CI Environment Reference</a></li>
-      <li><a href="/user/osx-ci-environment/">OSX CI Environment Reference</a></li>
+      <li><a href="/user/osx-ci-environment/">OS X CI Environment Reference</a></li>
       <li><a href="/user/trusty-ci-environment/">Trusty CI Environment</a><li>
       <li><a href="/user/environment-variables/">Environment Variables</a></li>
       <li><a href="/user/multi-os/">Building on Multiple Operating Systems</a></li>
@@ -85,13 +86,14 @@ <h3>Encrypting Files and Data</h3>
         <li><a href="/user/encryption-keys/">Encrypting Sensitive Data</a></li>
         <li><a href="/user/encrypting-files/">Encrypting Files</a></li>
         <li><a href="/user/github-oauth-scopes/">GitHub Permissions used by Travis CI</a></li>
+        <li><a href="/user/best-practices-security/">Best Practices in Securing Your Data</a></li>
       </ul>
 
       <h3>Beta Features</h3>
       <ul>
-        <li><a href="/user/customizing-the-build/#Building-only-the-latest-commit">Auto-cancellation</a></li>
         <li><a href="/user/cron-jobs/">Cron Jobs</a></li>
         <li><a href="/user/trusty-ci-environment/">Trusty Environment</a></li>
+        <li><a href="/user/build-stages/">Build Stages</a></li>
       </ul>
 
       <h3>Integrations and Notifications</h3>

_layouts/en.html

@@ -14,7 +14,7 @@
 
         <main id="main" class="main" data-swiftype-index='true'>
           {% unless page.no_header %}
-            <aside class="improve-page"><a href="{{ site.docs_github }}edit/gh-pages/{{ page.path }}" target="_blank" title="Edit this page on GitHub" class="button-pen" data-proofer-ignore>Improve this page on GitHub</a></aside>
+            <aside class="improve-page"><a href="{{ site.docs_github }}edit/master/{{ page.path }}" target="_blank" title="Edit this page on GitHub" class="button-pen" data-proofer-ignore>Improve this page on GitHub</a></aside>
             <h1 class="title">{{ page.title }}</h1>
           {% endunless %}
           {{ content }}

_plugins/select_env_var_generator.rb

@@ -0,0 +1,12 @@
+class SelectEnvVarGenerator < Jekyll::Generator
+  ENVS = %w(
+    WEBHOOK_PAYLOAD_GIST_ID
+  )
+  def generate(site)
+    site.config['env'] = {}
+
+    ENVS.each do |env|
+      site.config['env'][env] = ENV[env]
+    end
+  end
+end

_plugins/webhoook_payload_doc_handler.rb

@@ -0,0 +1,92 @@
+require 'faraday'
+require 'base64'
+require 'openssl'
+
+class WebhookPayloadDocHandler
+  DEFAULT_API_HOST = 'https://api.travis-ci.org'
+  API_HOST = ENV.fetch('API_HOST', DEFAULT_API_HOST)
+
+  def call(env)
+    req = Rack::Request.new(env)
+    gist_token = ENV['TRAVISBOT_GIST_TOKEN']
+    payload_gist_id = ENV['WEBHOOK_PAYLOAD_GIST_ID']
+
+    unless req.post? && gist_token && payload_gist_id
+      return invalid_req_response
+    end
+
+    payload = URI.decode(req.params["payload"])
+    sig = Base64.decode64 env["HTTP_SIGNATURE"]
+
+    pkey = OpenSSL::PKey::RSA.new(public_key)
+
+    unless pkey.verify(OpenSSL::Digest::SHA1.new, sig, payload)
+      return invalid_sig_response
+    end
+
+    conn = Faraday.new(:url => "https://api.github.com") do |faraday|
+      faraday.adapter Faraday.default_adapter
+    end
+
+    response = conn.patch "/gists/#{payload_gist_id}" do |req|
+      req.headers["Content-Type"] = 'application/json'
+      req.headers["Authorization"] = "token #{gist_token}"
+      req.body = gist_update_body(payload)
+    end
+
+    if response.success?
+      return valid_sig_response
+    else
+      return gist_update_failure_response
+    end
+  rescue
+    json_response(result: 'error', message: 'Internal server error', status: 500)
+  end
+
+  private
+  def public_key
+    return @public_key if @public_key
+
+    conn = Faraday.new(:url => API_HOST) do |faraday|
+      faraday.adapter Faraday.default_adapter
+    end
+    response = conn.get '/config'
+    @public_key = JSON.parse(response.body)["config"]["notifications"]["webhook"]["public_key"]
+  rescue
+    ''
+  end
+
+  def gist_update_body(payload)
+    {
+      "files" => {
+        "webhookpayload.json" => {
+          "content" => JSON.pretty_generate(JSON.load(payload))
+        }
+      }
+    }.to_json
+  end
+
+  def json_response(result:, message:, status: 200)
+    Rack::Response.new(
+      [{"result" => result, "message" => message}.to_json],
+      status,
+      {"Content-Type" => "application/json"}
+    )
+  end
+
+  def invalid_req_response
+    json_response(result: 'error', message: 'Invalid request.', status: 400)
+  end
+
+  def invalid_sig_response
+    json_response(result: 'error', message: 'Invalid signature.', status: 400)
+  end
+
+  def valid_sig_response
+    json_response(result: 'success', message: 'Signature is valid.')
+  end
+
+  def gist_update_failure_response
+    json_response(result: 'success', message: 'Signature is valid, but gist update failed.')
+  end
+end

api/index.html

@@ -371,7 +371,7 @@ <h2 id="creating-a-temporary-github-token">Creating a temporary GitHub token</h2
 <span class="nb">require</span> <span class="s1">'travis/tools/github'</span>
 
 <span class="c1"># drop_token will make the token a temporary one</span>
-<span class="n">github</span> <span class="o">=</span> <span class="no">Travis</span><span class="o">::</span><span class="no">Tools</span><span class="o">::</span><span class="no">Github</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="ss">drop_token: </span><span class="kp">true</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">g</span><span class="o">|</span>
+<span class="n">github</span> <span class="o">=</span> <span class="no">Travis</span><span class="o">::</span><span class="no">Tools</span><span class="o">::</span><span class="no">GitHub</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="ss">drop_token: </span><span class="kp">true</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">g</span><span class="o">|</span>
   <span class="n">g</span><span class="p">.</span><span class="nf">ask_login</span>    <span class="o">=</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"GitHub login:     "</span><span class="p">);</span> <span class="nb">gets</span> <span class="p">}</span>
   <span class="n">g</span><span class="p">.</span><span class="nf">ask_password</span> <span class="o">=</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"Password:         "</span><span class="p">);</span> <span class="nb">gets</span> <span class="p">}</span>
   <span class="n">g</span><span class="p">.</span><span class="nf">ask_otp</span>      <span class="o">=</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"Two-factor token: "</span><span class="p">);</span> <span class="nb">gets</span> <span class="p">}</span>