Add new Travis CI guide to documentation (vercel#160)

* Add new Travis CI docs * Implement feedback Co-Authored-By: Timothy <hello@timothy.is> * Improve Travis guide * Fix weird spacing in Code blocks * Better list order * Further Travis guide improvements * Give the first paragraph a context to Travis * Better titles
ijjk · May 31, 2018 · 0d0f6ba · 0d0f6ba
1 parent 121e791
commit 0d0f6ba
Show file tree

Hide file tree

Showing 5 changed files with 193 additions and 112 deletions.
diff --git a/lib/data/docs.js b/lib/data/docs.js
@@ -123,6 +123,15 @@ export default [
       {
         name: 'Redirect',
         href: '/docs/examples/redirect'
+      },
+      {
+        name: 'Continuous Integration',
+        posts: [
+          {
+            name: 'Travis CI',
+            href: '/docs/continuous-integration/travis'
+          }
+        ]
       }
     ]
   },
@@ -157,10 +166,6 @@ export default [
       {
         name: 'Create React App',
         href: '/docs/examples/create-react-app'
-      },
-      {
-        name: 'Travis CI',
-        href: '/docs/examples/travis'
       }
     ]
   },

diff --git a/lib/data/last-edited.json b/lib/data/last-edited.json
@@ -1,50 +1,52 @@
 {
-  "pages/docs/deployment-types/docker.js": "2018-05-25T16:55:53.821Z",
+  "pages/docs/continuous-integration/index.js": "2018-05-31T01:25:52.945Z",
+  "pages/docs/continuous-integration/travis.js": "2018-05-31T12:13:22.649Z",
+  "pages/docs/deployment-types/docker.js": "2018-05-31T01:25:52.824Z",
   "pages/docs/deployment-types/index.js": "2018-05-02T18:57:52.832Z",
   "pages/docs/deployment-types/lifecycle.js": "2018-05-02T18:57:52.832Z",
-  "pages/docs/deployment-types/node.js": "2018-05-25T16:55:53.822Z",
-  "pages/docs/deployment-types/static.js": "2018-05-25T16:55:53.822Z",
-  "pages/docs/examples/chat.js": "2018-05-25T16:55:53.823Z",
-  "pages/docs/examples/create-react-app.js": "2018-05-25T16:55:53.823Z",
+  "pages/docs/deployment-types/node.js": "2018-05-31T01:25:52.825Z",
+  "pages/docs/deployment-types/static.js": "2018-05-31T01:25:52.825Z",
+  "pages/docs/examples/chat.js": "2018-05-31T01:25:52.825Z",
+  "pages/docs/examples/create-react-app.js": "2018-05-31T01:25:52.826Z",
   "pages/docs/examples/graphql.js": "2018-05-02T18:57:52.834Z",
   "pages/docs/examples/index.js": "2018-05-02T18:57:52.834Z",
-  "pages/docs/examples/json-api.js": "2018-05-25T16:55:53.824Z",
-  "pages/docs/examples/next.js": "2018-05-25T16:55:53.825Z",
+  "pages/docs/examples/json-api.js": "2018-05-31T01:25:52.826Z",
+  "pages/docs/examples/next.js": "2018-05-31T01:25:52.826Z",
   "pages/docs/examples/redirect.js": "2018-05-02T18:57:52.834Z",
-  "pages/docs/examples/slack-slash.js": "2018-05-25T16:55:53.825Z",
-  "pages/docs/examples/static.js": "2018-05-25T16:55:53.826Z",
-  "pages/docs/examples/travis.js": "2018-05-25T16:55:53.826Z",
-  "pages/docs/features/aliases.js": "2018-05-25T16:55:53.827Z",
-  "pages/docs/features/certs.js": "2018-05-25T16:55:53.828Z",
-  "pages/docs/features/configuration.js": "2018-05-25T16:55:53.829Z",
-  "pages/docs/features/dns.js": "2018-05-25T16:55:53.829Z",
-  "pages/docs/features/env-and-secrets.js": "2018-05-25T16:55:53.830Z",
+  "pages/docs/examples/slack-slash.js": "2018-05-31T01:25:52.827Z",
+  "pages/docs/examples/static.js": "2018-05-31T01:25:52.827Z",
+  "pages/docs/examples/travis.js": "2018-05-31T01:26:23.927Z",
+  "pages/docs/features/aliases.js": "2018-05-31T01:25:52.828Z",
+  "pages/docs/features/certs.js": "2018-05-31T01:25:52.828Z",
+  "pages/docs/features/configuration.js": "2018-05-31T01:25:52.829Z",
+  "pages/docs/features/dns.js": "2018-05-31T01:25:52.829Z",
+  "pages/docs/features/env-and-secrets.js": "2018-05-31T01:25:52.829Z",
   "pages/docs/features/index.js": "2018-05-02T18:57:52.836Z",
-  "pages/docs/features/now-cli.js": "2018-05-25T16:55:53.830Z",
-  "pages/docs/features/path-aliases.js": "2018-05-25T16:55:53.831Z",
-  "pages/docs/features/private-npm.js": "2018-05-25T16:55:53.832Z",
-  "pages/docs/features/repositories.js": "2018-05-25T16:55:53.832Z",
-  "pages/docs/features/scaling.js": "2018-05-25T16:55:53.832Z",
+  "pages/docs/features/now-cli.js": "2018-05-31T01:25:52.830Z",
+  "pages/docs/features/path-aliases.js": "2018-05-31T01:25:52.830Z",
+  "pages/docs/features/private-npm.js": "2018-05-31T01:25:52.830Z",
+  "pages/docs/features/repositories.js": "2018-05-31T01:25:52.831Z",
+  "pages/docs/features/scaling.js": "2018-05-31T01:25:52.831Z",
   "pages/docs/features/zero-downtime-migration.js": "2018-05-02T18:57:52.837Z",
-  "pages/docs/getting-started/assign-a-domain-name.js": "2018-05-25T16:55:53.833Z",
-  "pages/docs/getting-started/deployment.js": "2018-05-25T16:55:53.834Z",
-  "pages/docs/getting-started/environment-variables.js": "2018-05-25T16:55:53.834Z",
-  "pages/docs/getting-started/five-minute-guide-to-now.js": "2018-05-26T00:50:19.929Z",
+  "pages/docs/getting-started/assign-a-domain-name.js": "2018-05-31T01:25:52.831Z",
+  "pages/docs/getting-started/deployment.js": "2018-05-31T01:25:52.832Z",
+  "pages/docs/getting-started/environment-variables.js": "2018-05-31T01:25:52.832Z",
+  "pages/docs/getting-started/five-minute-guide-to-now.js": "2018-05-31T01:25:52.832Z",
   "pages/docs/getting-started/index.js": "2018-05-02T18:57:52.838Z",
-  "pages/docs/getting-started/logs.js": "2018-05-25T16:55:53.836Z",
-  "pages/docs/getting-started/scaling.js": "2018-05-25T16:55:53.836Z",
-  "pages/docs/getting-started/secrets.js": "2018-05-25T16:55:53.837Z",
-  "pages/docs/getting-started/whats-next.js": "2018-05-25T16:55:53.837Z",
-  "pages/docs/guides/app-lifecycle-and-scalability.js": "2018-05-25T16:55:53.838Z",
-  "pages/docs/guides/how-to-use-cloudflare.js": "2018-05-25T16:55:53.838Z",
+  "pages/docs/getting-started/logs.js": "2018-05-31T01:25:52.833Z",
+  "pages/docs/getting-started/scaling.js": "2018-05-31T01:25:52.833Z",
+  "pages/docs/getting-started/secrets.js": "2018-05-31T01:25:52.833Z",
+  "pages/docs/getting-started/whats-next.js": "2018-05-31T01:25:52.833Z",
+  "pages/docs/guides/app-lifecycle-and-scalability.js": "2018-05-31T01:25:52.834Z",
+  "pages/docs/guides/how-to-use-cloudflare.js": "2018-05-31T01:25:52.834Z",
   "pages/docs/guides/index.js": "2018-05-02T18:57:52.839Z",
-  "pages/docs/guides/migrate-your-app.js": "2018-05-25T16:55:53.839Z",
-  "pages/docs/guides/redirect.js": "2018-05-25T16:55:53.839Z",
-  "pages/docs/guides/updating-now-cli.js": "2018-05-25T16:55:53.840Z",
-  "pages/docs/index.js": "2018-05-26T00:55:13.000Z",
+  "pages/docs/guides/migrate-your-app.js": "2018-05-31T01:25:52.835Z",
+  "pages/docs/guides/redirect.js": "2018-05-31T01:25:52.835Z",
+  "pages/docs/guides/updating-now-cli.js": "2018-05-31T01:25:52.835Z",
+  "pages/docs/index.js": "2018-05-31T11:59:54.000Z",
   "pages/docs/other/billing.js": "2018-05-25T16:55:53.840Z",
-  "pages/docs/other/faq.js": "2018-05-26T00:56:28.670Z",
+  "pages/docs/other/faq.js": "2018-05-31T01:25:52.836Z",
   "pages/docs/other/index.js": "2018-05-02T18:57:52.841Z",
-  "pages/docs/other/restrictions.js": "2018-05-25T16:55:53.842Z",
-  "pages/docs/other/support-channels.js": "2018-05-25T16:55:53.842Z"
+  "pages/docs/other/restrictions.js": "2018-05-31T01:25:52.836Z",
+  "pages/docs/other/support-channels.js": "2018-05-31T01:25:52.836Z"
 }
diff --git a/pages/docs/continuous-integration/index.js b/pages/docs/continuous-integration/index.js
@@ -0,0 +1,4 @@
+// Helpers
+import redirect from '../../../lib/redirect'
+
+export default redirect('/docs')
diff --git a/pages/docs/continuous-integration/travis.js b/pages/docs/continuous-integration/travis.js
@@ -0,0 +1,138 @@
+import markdown from 'markdown-in-js'
+import withDoc, { components } from '../../../lib/with-doc'
+
+import { devisscher, sergio } from '../../../lib/data/team'
+import { Code, InlineCode } from '../../../components/text/code'
+import { TerminalInput } from '../../../components/text/terminal'
+import Caption from '../../../components/text/caption'
+
+// prettier-ignore
+export default withDoc({
+  title: 'Continuous Integration with Travis CI',
+  date: '13 Mar 2018',
+  authors: [devisscher, sergio],
+  editUrl: 'pages/docs/continuous-integration/travis.js'
+})(markdown(components)`
+
+Travis Ci is a Continuous Integration tool that lets you automate the build and deployment of your project when something new is pushed to a GitHub repository.
+
+In this guide we will setup our Travis CI pipeline to:
+- Create a new deployment after each push to any branch
+- [Alias](/docs/features/aliases) your deployment made on the master branch with your [custom domain](/docs/getting-started/assign-a-domain-name)
+- Optionally; build an application inside Travis instead of with Now
+
+## Step 1: Getting a Now Token
+
+The first thing you'll need is a token for your account. You can get this in the [Tokens section](/account/tokens) of your Account Settings.
+
+Head to the tokens page of your dashboard by navigating to your Account Settings and then clicking the "Tokens" link.
+
+By entering a name into the input labelled "Create a new token..." and subsequently pressing <kbd>Enter</kbd>, a new token will be created which you can copy to your clipboard by clicking ${<InlineCode>Copy</InlineCode>}.
+
+With this token you can use Now with your account anywhere with the following command:
+
+${<TerminalInput>now --token [TOKEN]</TerminalInput>}
+
+${<Caption>Replace {<InlineCode>--token</InlineCode>} with {<InlineCode>-t</InlineCode>} for short.</Caption>}
+
+The ${<InlineCode>[TOKEN]</InlineCode>} in the example command is replaced with token you copied from your Account Settings.
+
+## Step 2: Preparing your project to use Travis
+
+First of all, make sure you've signed up with Travis and synced the repositories you'd like to use with Now previous to this. If you have yet to do this, read steps 1 and 2 of the Travis CI's ["To get started with Travis CI" guide](https://docs.travis-ci.com/user/getting-started). If you're configuring a public repository, you can use [travis-ci.org](https://travis-ci.org), otherwise if the repository is private, you'll need to use the paid version on [travis-ci.com](https://travis-ci.com).
+
+Now that you have your token and have set up your GitHub account with Travis, you can start integrating Travis into your project. Start by creating a ${<InlineCode>.travis.yml</InlineCode>} file in the root of your repository.
+
+Next, go to the desired repository's settings in Travis (e.g. ${<InlineCode>https://travis-ci.org/:username/:repositroy/settings</InlineCode>}) and add a new environment variable with the value of your newly created Now token. If you call it ${<InlineCode>NOW_TOKEN</InlineCode>} you can then use it inside Travis CI configuration like the following for example:
+
+${<TerminalInput>now --token $NOW_TOKEN</TerminalInput>}
+
+> *Note*: You can use any name for your environment variable, just change the name that you entered into the repositories settings in Travis CI with your own variable name and then use that name with ${<InlineCode>$</InlineCode>} at the beginning like the example above.
+
+## Step 3: Configuring Travis to deploy with Now using your Token
+
+Now that Travis is integrated into your repository, you need to configure your Travis pipeline. In order to do that you need to change your ${<InlineCode>.travis.yml</InlineCode>} file and add the following content:
+
+${<Code>{
+`language: node_js
+node_js:
+  - "node"
+cache:
+  directories:
+    - "node_modules" # This will tell Travis CI to cache the dependencies
+script: npm test # Here you could also run the build step of your application
+before_deploy: npm install now --no-save # Install Now CLI on Travis
+deploy:
+  - provider: script # Run a custom deployment script which we will define below
+    script: now --token $NOW_TOKEN
+    skip_cleanup: true
+    on:
+      all_branches: true
+      master: false
+  - provider: script
+    script: now --token $NOW_TOKEN && now alias --token $NOW_TOKEN
+    skip_cleanup: true
+    on:
+      master: true
+`}</Code>}
+
+> *Note*: If you are deploying using an OSS account you will have to add the ${<InlineCode>--public</InlineCode>} argument with the Now commands to avoid being asked if you are sure you want your deployment to be public, which will block the build; awaiting user input.
+
+As you may have noticed, the above script for the master branch uses the ${<InlineCode>now alias</InlineCode>} command without providing the deployment URL and the alias to use. This can be achieved [using a configuration file](/docs/features/configuration). You can read more about it in ["How Do I Deploy and Alias in a Single Command?"](/docs/other/faq#how-do-i-deploy-and-alias-in-a-single-command) on our FAQ page.
+
+And that's it! Everytime you push something new to any branch it will create a new deployment and if the branch is master it will also move the project aliases to it.
+
+## Optional: Avoid building on Now (Instead build on Travis)
+
+In some cases you may prefer to build on Travis CI instead of directly on Now. If that's the case, this can be achieved modifying your ${<InlineCode>.travis.yml</InlineCode>} and ${<InlineCode>now.json</InlineCode>} files a little bit.
+
+### Defining what to deploy
+
+If you decide to build your application on Travis CI you will not need to deploy your source code, if that's the case you can use a [configuration file with the ${<InlineCode>files</InlineCode>} key](/docs/features/configuration#files-(array)) to specify what to deploy.
+
+If you are building a [Next.js](https://github.com/zeit/next.js) application with a [custom server](https://github.com/zeit/next.js#custom-server-and-routing) you can add the following to your configuration file.
+
+${<Code>{
+`{
+  ...
+  "files": [
+    ".next",
+    "server",
+    "static,
+    "package.json",
+    "yarn.lock"
+  ],
+  ...
+}
+`}</Code>}
+
+With this, Now will only deploy the files under the directories ${<InlineCode>.next</InlineCode>}, ${<InlineCode>server</InlineCode>}, ${<InlineCode>static</InlineCode>}, and the files ${<InlineCode>package.json</InlineCode>} and ${<InlineCode>yarn.lock</InlineCode>}. You can customize this to add any files which will be required by your application after the build step.
+
+### Building on Travis
+
+To run your build on Travis CI you only need to change your ${<InlineCode>.travis.yml</InlineCode>} file to run the build script. To do this, change the ${<InlineCode>script</InlineCode>} part of your file as follows:
+
+${<Code>{
+`...
+script: npm run build
+...
+`}</Code>}
+
+> *Note*: This will make Travis CI run the build script instead of the test script, you can add a prebuild or postbuild step to run tests
+
+Since you are building your application on Travis, you don't want Now to try to build it. To avoid this you can add the following simple script to your ${<InlineCode>package.json</InlineCode>}.
+
+${<Code>{
+`{
+  ...
+  "scripts": {
+    ...
+    "now-build": "echo 'Built on Travis CI'",
+    ...
+  }
+  ...
+}
+`}</Code>}
+
+If the ${<InlineCode>now-build</InlineCode>} script is defined, Now will use it instead of ${<InlineCode>build</InlineCode>}. This lets you define it yourself in order to customize the build step on Now or just avoid building it on Now entirely.
+`)
diff --git a/pages/docs/examples/travis.js b/pages/docs/examples/travis.js
@@ -1,72 +1,4 @@
-import markdown from 'markdown-in-js'
-import withDoc, { components } from '../../../lib/with-doc'
-import { devisscher } from '../../../lib/data/team'
-import { TerminalInput } from '../../../components/text/terminal'
-import { Code, InlineCode } from '../../../components/text/code'
+// Helpers
+import redirect from '../../../lib/redirect'
 
-// prettier-ignore
-export default withDoc({
-  title: 'Automate Deployment with Travis CI',
-  description: 'Using Travis CI to automate your Now deployments',
-  date: '04 November 2017',
-  authors: [devisscher],
-  editUrl: 'pages/docs/examples/travis.js',
-})(markdown(components)`
-
-You might want to automate your Now deployments. Here is how you can achieve this by using Git and Travis. Every time you push or merge to the master branch a new build and deployment is initiated in Travis CI.
-
-1. You need to get a [token](https://zeit.co/account/tokens). Go to the tokens page of your dashboard, under Account Settings, Tokens. Enter the name of the Token (e.g. Travis CI) and hit enter. A new token will be created which you can copy to your clipboard by clicking Copy.
-2. Create a .travis.yml file in the root of your project.
-3. Generate a secure variable for your ZEIT token by running the following command with the token you obtained from your ZEIT account. (You need to install [The Travis Client](https://github.com/travis-ci/travis.rb#installation)):
-
-${<TerminalInput>travis encrypt -r username/repo NOW_TOKEN=xxxxxxxxxxxxxxxxxxxxxxx --add</TerminalInput>}
-
-4. Now open your .travis.yml file and add the following:
-
-${
-<Code>{
-`language: node_js
-node_js:
-- "node"
-cache: npm
-script: npm run deploy
-after_script: npm run alias
-env:
-global:
-    secure: <this is your encrypted NOW token. It was added when you ran travis encrypt>
-`}
-</Code>}
-
-5. Open your package.json file and add the following
-information, adapted for your own deployment. This is used to run the alias command and point your
-domain to the correct deployment (you could also put
-this in a [now.json](https://zeit.co/blog/now-json) file):
-
-${
-<Code>{`{
-    ...
-    "now": {
-        "name": "example",
-        "alias": "example.com"
-        }
-    ...
-}`}</Code>}
-
-6. Also add the following 2 scripts to the ${<InlineCode>script</InlineCode>} property in your package.json file. These are used by your Travis config. The first is to deploy and the second is used to alias your latest deploy:
-
-${
-<Code>{`{
-    ...
-    "scripts": {
-    ...
-        "deploy": "now -e NODE_ENV=production --token $NOW_TOKEN --npm",
-        "alias": "now alias --token=$NOW_TOKEN"
-        }
-    }
-}`}
-</Code>
-}
-
-7. Test it out by committing your code to Github. Check out your [travis-ci.org](https://travis-ci.org) build feed.
-
-`)
+export default redirect('/docs/continuous-integration/travis')