Tag: GitHub

Git Gateway Backend

admin

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 instead.)

Git Gateway with Netlify

The Netlify Identity service can handle the authentication and provides a simple interface for user management. The Netlify CMS featured templates are working examples of this backend.

To use it in your own project stored on GitHub or GitLab, follow these steps:

  1. Head over to the Netlify Identity docs and follow the steps to get started.
  2. Add the following lines to your Netlify CMS config.yml file:
backend:
  name: git-gateway

Reconnect after Changing Repository Permissions

If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the Netlify Git Gateway docs.

Git Gateway without Netlify

You can use Git Gateway without Netlify by setting up your own Git Gateway server and connecting it with your own instance of GoTrue (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).

To configure in Netlify CMS, use the same backend settings in your Netlify CMS config.yml file as described in Step 2 of the Git Gateway with Netlify Identity instructions above.

Authentication Providers

admin

Authentication Providers

One challenge for frontend projects is handling authentication. OAuth2 is a widely accepted standard used by many services and APIs, but the OAuth authentication process requires a server to send a signed request to the OAuth server, signed with a secret that you can never expose to the client side of your application.

Netlify solves this problem by providing an integrated service that will sign the OAuth requests for you and give back an access token ready to use.

Netlify currently supports authentication with GitHub, GitLab, and Bitbucket.

#Enable OAuth for a Netlify site

While the below workflow is specifically for GitHub, the GitLab and Bitbucket workflows are similar.

Before you can use an authentication provider, you need to:

  1. register an API application with the OAuth provider
  2. configure credentials in the Netlify UI

#OAuth provider setup

You need to create an API application and make note of the Client ID and a Client Secret so that you can use them in your Netlify configuration.

  1. In GitHub, go to your account Settings and select Developer Settings, then OAuth Apps or use this shortcut.
  2. Select Register a new application.
  3. For the Authorization callback URL, enter https://web.archive.org/web/20220805155937/https://api.netlify.com/auth/done. The other fields can contain anything you want.
  4. On your new application’s GitHub overview page, make note of the Client ID.
  5. Generate a Client Secret and make note of it for later. You can’t access this secret again.

#Netlify UI settings

When you complete application registration with GitHub, you need to add the Client ID and Client Secret to your Netlify site:

  1. Go to Site settings > Access control > OAuth.
  2. Under Authentication Providers, select Install Provider.
  3. Select GitHub and enter the Client ID and Client Secret from earlier, then save.

#Site usage example

Once you’ve configured an authentication provider, you can use it to obtain an access token in your application.

You can preview the OAuth user experience in our demo.

Here’s an example of how to ask users to authenticate with GitHub and use the resulting token in your application’s calls to the GitHub API:

<!DOCTYPE html>
<html>
  <head>
    <title>GitHub Authentication Example</title>

    <!-- Make sure to include Netlify’s authentication library -->
    <!-- Also available from npm as netlify-auth-providers -->
    <script src="https://web.archive.org/web/20220805155937/https://unpkg.com/netlify-auth-providers"></script>
  </head>
  <body>
    <h1>GitHub Authentication Example:</h1>
    <p><a href="#" id="login">Authenticate</a></p>
    <p>Token: <span id="output-token">Not authenticated yet</span></p>
    <p>
      User emails:
      <span id="output-email">Not authenticated yet</span>
    </p>

    <script>
      const anchorTag = document.getElementById("login");
      const outputToken = document.getElementById("output-token");
      const outputEmail = document.getElementById("output-email");

      anchorTag.addEventListener("click", (event) => {
        event.preventDefault();

        const authenticator = new netlify.default({});

        authenticator.authenticate(
          // Set the OAuth provider and token scope
          // Provider can be "github", "gitlab", or "bitbucket"
          // The scopes available depend on your OAuth provider
          { provider: "github", scope: "user" },
          async function (error, data) {
            if (error) {
              outputToken.innerText =
                "Error Authenticating with GitHub: " + error;
            } else {
              outputToken.innerText =
                "Authenticated with GitHub. Access Token: " +
                data.token;
              outputEmail.innerText = await loadGitHubUserEmails(
                data.token
              );
            }
          }
        );
      });

      async function loadGitHubUserEmails(token) {
        return await fetch("https://web.archive.org/web/20220805155937/https://api.github.com/user/emails", {
          headers: {
            Accept: "application/vnd.github.v3+json",
            Authorization: `token ${token}`,
          },
        })
          .then((response) => response.json())
          .then((response) => JSON.stringify(response));
      }
    </script>
  </body>
</html> OAuth tokens are scoped to limit access. Each OAuth provider has different scopes you can use in your application. In the above GitHub example, the scope is set to user, which has read and write access to profile information. If you don’t provide a scope, OAuth providers usually apply the default scope to your token. Default scopes typically only have read access to public information. You can find a list of scopes for supported OAuth providers below: GitHub GitLab Bitbucket

GitLab Backend

admin

GitLab

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.

Note: GitLab default branch is protected by default, thus typically requires maintainer permissions in order for users to have push access.

The GitLab API allows for two types of OAuth2 flows:

  • Web Application Flow, which works much like the GitHub OAuth flow described above.
  • Implicit Grant, which operates without the need for an authentication server.

Web Application Flow with Netlify

When using GitLab’s Web Application Flow for authentication, you can use Netlify to handle the server-side authentication requests.

To enable it:

  1. Follow the GitLab docs to add your Netlify CMS instance as an OAuth application. For the Redirect URI, enter https://api.netlify.com/auth/done, and check the box for api scope.
  2. Follow the Netlify docs to add your new GitLab Application ID and Secret to your Netlify site dashboard.
  3. In your repository, add the following lines to your Netlify CMS config.yml file:
backend:
  name: gitlab
  repo: owner-name/repo-name # Path to your GitLab repository

Client-Side Implicit Grant (GitLab)

With GitLab’s Implicit Grant, users can authenticate with GitLab directly from the client. To do this:

  1. Follow the GitLab docs to add your Netlify CMS instance as an OAuth application. For the Redirect URI, enter the address where you access Netlify CMS, for example, https://www.mysite.com/admin/. For scope, select api.
  2. GitLab gives you an Application ID. Copy this ID and enter it in your Netlify CMS config.yml file, along with the following settings: 
    backend:
 name: gitlab
 repo: owner-name/repo-name # Path to your GitLab repository
 auth_type: implicit # Required for implicit grant
 app_id: your-app-id # Application ID from your GitLab settings

    You can also use Implicit Grant with a self-hosted GitLab instance. This requires adding api_root, base_url, and auth_endpoint fields:

    backend:
 name: gitlab
 repo: owner-name/repo-name # Path to your GitLab repository
 auth_type: implicit # Required for implicit grant
 app_id: your-app-id # Application ID from your GitLab settings
 api_root: https://my-hosted-gitlab-instance.com/api/v4
 base_url: https://my-hosted-gitlab-instance.com
 auth_endpoint: oauth/authorize

Note: In both cases, GitLab also provides you with a client secret. You should never store this in your repo or reveal it in the client.

Netlify CMS 2.4.0 brings deploy preview links!

admin

Netlify CMS 2.4.0 brings deploy preview links!

Seeing is believing

The editorial workflow allows editors to create draft content in Netlify CMS, and Netlify can provide deploy previews of draft content, but there hasn’t been a way to access links to these preview builds from within Netlify CMS. The preview pane in the editor is a good tool for seeing how content will look on the site, but in the words of Marvin Gaye, “ain’t nothing like the real thing!” As Mr. Gaye bemoaned the absence of his beloved, so content creators long for the warm embrace of an actual production build. Their words, not ours.

Solution: GitHub Statuses

For sites using the GitHub (or Git Gateway with GitHub) backend, we now have deploy preview links in the CMS using the GitHub Statuses API. Many static sites already have continuous deployment and deploy previews configured on their repo, and they often use statuses to provide a link to a deployment directly from a commit or pull request. To retrieve a commit status that provides a deploy preview URL, we check for a status whose “context” contains one of a list of keywords commonly associated with deploy previews.

If a status is not found, nothing happens in the UI. If a status is found, but the deploy preview isn’t ready, we provide a “Check for Preview” link, allowing the content editor to manually check back until the preview is ready:

When the preview is ready, the “Check for Preview” button is replaced with a link to the content:

Deploy preview links generally direct to the root of a site, but Netlify CMS can also link straight to the piece of content being edited. By providing a string template for each collection, you can get links that go right where editors expect them to. More complex URL’s can be constructed using date information from your content files.

Unpublished vs. published

If you’re not using the editorial workflow, you may not feel you need this very much. Whenever you save content, it’s immediatlely published, so you can navigate to your live site to see the changes. That said, it’s at least convenient to have a link direct to your content from the CMS, so deploy preview links can also work for CMS installs that do not use the editorial workflow. Instead of retrieving a URL from a commit status, this functionality requires setting a site_url in your config, and that URL is used in place of the deploy preview URL.

GitLab and Bitbucket

Support is coming soon for these two awesome backends! Stay tuned.

Try it out!

Deploy preview links are live in Netlify CMS 2.4.0. Please give them a try and let us know if you have any problems by opening an issue or reaching out in our community chat!

Contributor Guide

admin

We’re hoping that Netlify CMS will do for the Jamstack what WordPress did for dynamic sites back in the day. We know we can’t do that without building a thriving community of contributors and users, and we’d love to have you join us.

Getting started with contributing

Being a developer is not a requirement for contributing to Netlify CMS, you only need the desire, a web browser, and a GitHub account. The GitHub repo has a step-by-step guide to get started with the code.

The basics of the Netlify CMS docs

The documentation for Netlify CMS is written in Markdown (a good cheatsheet on Markdown is here), with the source residing on GitHub in the /website/content/docs folder.

The GitHub website allows you to submit issues, work with files, search for content, and browse changes that have been submitted in the past and those that are being submitted now (aka Pull Requests).

Style guidelines

A style guide is available to help provide context around grammar, code styling, syntax, etc.

Filing issues

If you have a GitHub account, you can file an issue (aka bug report) against the Netlify CMS docs. Even if you’re not able to, or don’t know how to, fix the issue (see Improve existing content), it helps to start the conversation.

When filing an issue, it is important to remember the Code of Conduct.

Improve existing content

If you are able to offer up a change to existing content, we welcome this. Once you’ve forked the repo, and changed the content, you would file a pull request (PR). The repo Contributing file lays out the correct format for PRs.

Other places to get involved

While we work on building this page (and you can help!), here are some links with more information about getting involved:

  • Setup instructions and Contribution Guidelines
  • Join our Community Chat
  • Code of Conduct
  • Project Milestones
  • Good First Issues