From d6c03707d8ef4e2fe4b70f38896e17e67ba9dc1b Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Tue, 24 Jul 2018 17:33:53 -0700 Subject: [PATCH] Update docs to add Bitbucket support (#1512) * Update docs to add Bitbucket support * Update doc to remove Git Gateway support for BB * Update Bitbucket info based on review --- website/site/content/docs/add-to-your-site.md | 10 +++-- .../content/docs/authentication-backends.md | 43 +++++++++++-------- website/site/content/docs/intro.md | 4 +- .../content/docs/start-with-a-template.md | 1 + 4 files changed, 35 insertions(+), 23 deletions(-) diff --git a/website/site/content/docs/add-to-your-site.md b/website/site/content/docs/add-to-your-site.md index 4bf87d66..c5d21d41 100755 --- a/website/site/content/docs/add-to-your-site.md +++ b/website/site/content/docs/add-to-your-site.md @@ -8,7 +8,7 @@ menu: # Add Netlify CMS to Your Site -Netlify CMS is adaptable to a wide variety of projects. The only inflexible requirement is that your site content must be written in markdown, JSON, YAML, or TOML files, stored in a repo on [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/). You can also create your own custom backend, or if you're interested in Bitbucket support, that's [coming soon](https://github.com/netlify/netlify-cms/pull/525). +Netlify CMS is adaptable to a wide variety of projects. It works with any content written in markdown, JSON, YAML, or TOML files, stored in a repo on [GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), or [Bitbucket](https://bitbucket.org). You can also create your own custom backend. This tutorial will guide you through the steps for adding Netlify CMS to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Hugo, Hexo, or Gatsby. Alternatively, you can [start from a template](https://www.netlifycms.org/docs/start-with-a-template) or dive right into to [configuration options](https://www.netlifycms.org/docs/configuration-options). @@ -80,7 +80,9 @@ Configuration will be different for every site, so we'll break it down into part ### Backend -We're using [Netlify](https://www.netlify.com) for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward. You can start your Netlify CMS `config.yml` file with these lines: +We're using [Netlify](https://www.netlify.com) for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward. + +For GitHub and GitLab repositories, you can start your Netlify CMS `config.yml` file with these lines: ```yaml backend: @@ -88,7 +90,9 @@ backend: branch: master # Branch to update (optional; defaults to master) ``` -These lines specify your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We'll get to the details of that in the [Authentication section](#authentication) below.) If you leave out the `branch` declaration, it will default to `master`. +_(For Bitbucket repositories, use the [Bitbucket backend](https://www.netlifycms.org/docs/authentication-backends/#bitbucket-backend) instructions instead.)_ + +The configuration above specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We'll get to the details of that in the [Authentication section](#authentication) below.) If you leave out the `branch` declaration, it will default to `master`. ### Editorial Workflow diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index ec95b882..84308cf0 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -7,15 +7,15 @@ menu: --- # Authentication & Backends -Netlify CMS stores content in your GitHub or GitLab repository. (Bitbucket [coming soon](https://github.com/netlify/netlify-cms/pull/525)!) In order for this to work, you need to authenticate with your Git host, and in most cases that requires a server. We have a few options for handling this. +Netlify CMS stores content in your GitHub, GitLab, or Bitbucket repository. In order for this to work, you need to authenticate with your Git host, and in most cases that requires a server. We have a few options for handling this. **Note:** some static site generators have plugins for optimized integration with Netlify CMS, and starter templates may utilize these plugins. If you're using a starter template, read the template documentation before proceeding, as their instructions may differ. ## Git Gateway with Netlify Identity -[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct push access to your GitHub or GitLab repository. [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](https://www.netlifycms.org/docs/start-with-a-template) are working examples of this backend. +[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct write access to your GitHub or GitLab repository. (For Bitbucket repositories, use the [Bitbucket backend](#bitbucket-backend) instead.) [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](https://www.netlifycms.org/docs/start-with-a-template) are working examples of this backend. -To use it in your own project, follow these steps: +To use it in your own project stored on GitHub or GitLab, follow these steps: 1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the steps to get started. @@ -56,14 +56,16 @@ To enable it: ```yaml backend: name: github - repo: owner-name/repo-name # Path to your Github repository + repo: owner-name/repo-name # Path to your GitHub repository ``` +If you prefer to run your own authentication server, check out the section on [external OAuth clients](#external-oauth-clients). + ## GitLab Backend For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work. -Unlike GitHub, the GitLab API allows for two types of OAuth2 flows: [Web Application Flow](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above, and [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#implicit-grant), which operates _without_ the need for an authentication server. +The GitLab API allows for two types of OAuth2 flows: [Web Application Flow](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above, and [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#implicit-grant), which operates _without_ the need for an authentication server. ### Web Application Flow with Netlify @@ -112,14 +114,21 @@ With GitLab's Implicit Grant, users can authenticate with GitLab directly from t Note that in both cases, GitLab will also provide you with a client secret. You should _never_ store this in your repo or reveal it in the client. -## Bitbucket Support +## Bitbucket Backend -Netlify CMS is meant to be platform agnostic, so we’re always looking to expand the ecosystem and -find new ways to use it. Check out our active PR in progress for -[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) backend support. +For repositories stored on Bitbucket, the `bitbucket` backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work. -Git Gateway could also be modified to support other Git hosts. If you're interested, you can file an -issue (or a pull request!) in the [git-gateway repo](https://github.com/netlify/git-gateway). +To enable it: + +1. Follow the authentication provider setup steps in the [Netlify + docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider). +2. Add the following lines to your Netlify CMS `config.yml` file: + + ```yaml + backend: + name: bitbucket + repo: owner-name/repo-name # Path to your Bitbucket repository + ``` ## External OAuth Clients @@ -137,16 +146,14 @@ Check each project's documentation for instructions on how to configure it. ## Options -The `git-gateway`, `github`, and `gitlab` backends all allow some additional optional fields for certain use -cases. A full reference is below. Note that these are properties of the `backend` field, and should -be nested under that field. +Netlify CMS backends allow some additional fields for certain use cases. A full reference is below. Note that these are properties of the `backend` field, and should be nested under that field. | Field | Default | Description | | --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `repo` | none | **Required** for `github` and `gitlab` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. | +| `repo` | none | **Required** for `github`, `gitlab`, and `bitbucket` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. | | `accept_roles` | none | `git-gateway` only. Limits CMS access to your defined array of user roles. Omitting this field gives access to all registered users. | | `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. | -| `api_root` | `https://api.github.com` (GitHub) or `https://gitlab.com/api/v4` (GitLab) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. | +| `api_root` | `https://api.github.com` (GitHub), `https://gitlab.com/api/v4` (GitLab), or `https://api.bitbucket.org/2.0` (Bitbucket) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. | | `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. | -| `base_url` | `https://api.netlify.com` (GitHub) or `https://gitlab.com` (GitLab) | OAuth client URL. **Required** when using an external OAuth server or self-hosted GitLab. | -| `auth_endpoint` | `auth` (GitHub) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. | +| `base_url` | `https://api.netlify.com` (GitHub, Bitbucket) or `https://gitlab.com` (GitLab) | OAuth client URL. **Required** when using an external OAuth server or self-hosted GitLab. | +| `auth_endpoint` | `auth` (GitHub, Bitbucket) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. | diff --git a/website/site/content/docs/intro.md b/website/site/content/docs/intro.md index d987d60b..5e630be8 100755 --- a/website/site/content/docs/intro.md +++ b/website/site/content/docs/intro.md @@ -10,12 +10,12 @@ menu: Netlify CMS is an open source content management system for your Git workflow that enables you to provide editors with friendly UI and intuitive workflow. You can use it with any static site generator to create faster, more flexible web projects. Content is stored in your Git repository alongside your code for easier versioning, multi-channel publishing, and the option to handle content updates directly in Git. -At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub or GitLab API. This provides many advantages, including: +At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub, GitLab, or Bitbucket API. This provides many advantages, including: * **Fast, web-based UI:** with rich-text editing, real-time preview, and drag-and-drop media uploads. * **Platform agnostic:** works with most static site generators. * **Easy installation:** add two files to your site and hook up the backend by including in your build process or linking to our CDN. -* **Modern authentication:** using GitHub or GitLab and JSON web tokens. +* **Modern authentication:** using GitHub, GitLab, or Bitbucket and JSON web tokens. * **Flexible content types:** specify an unlimited number of content types with custom fields. * **Fully extensible:** create custom-styled previews, UI widgets, and editor plugins. diff --git a/website/site/content/docs/start-with-a-template.md b/website/site/content/docs/start-with-a-template.md index e6f4f31f..5d0b2072 100644 --- a/website/site/content/docs/start-with-a-template.md +++ b/website/site/content/docs/start-with-a-template.md @@ -23,6 +23,7 @@ Netlify CMS can be [added to an existing site](https://www.netlifycms.org/docs/a After clicking one of those buttons, you’ll authenticate with GitHub or GitLab and choose a repository name. Netlify will then automatically create a clone of the repository in your GitHub or GitLab account. Next, it will build and deploy the new site on Netlify, bringing you to the site dashboard when the build is complete. +**Note for Bitbucket users:** Netlify CMS supports Bitbucket repositories, but Bitbucket's permissions won't work with the Deploy to Netlify buttons above. You can still set up a repository manually, or follow the [tutorial](https://www.netlifycms.org/docs/add-to-your-site) for adding Netlify CMS to an existing site. ## Access Netlify CMS on your new site