Integrating Web Author with Git (GitHub, GitLab, Bitbucket)
Edit online

Oxygen XML Web Author includes a built-in Git Plugin that allows you to edit files stored in a Git repository (with GitHub, GitLab, and Bitbucket integrations). The Git Plugin allows you to access repositories simply by using your GitHub, GitLab, or Bitbucket login credentials.

GitHub Integration

You can configure your Git plugin to allow OAuth 2.0 authentication for GitHub integrations to access files stored in a public or private repository. You will then have access to a Login with GitHub button in the Git Login dialog box. You can configure your integration either by using github.com or with a GitHub Enterprise deployment.

Figure 1: GitHub Login Dialog Box

Configuring a Git Integration with github.com

To configure your Git integration using github.com, follow this procedure:
  1. Log in to GitHub and register a new OAuth application at https://github.com/settings/applications/new.
    1. Complete the form.
    2. The Authorization callback URL field should include the following path: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/github-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
  2. Click on Register application to obtain the Client ID and Client Secret credentials (they are displayed at the top-right section of the resulting page).
  3. Set your Client ID and Client Secret credentials in your plugin configuration by doing the following:
    1. Go to the Administration Page.

    2. In the Plugins section, click on the Configure icon for the Git plugin and select the GitHub tab.

      Figure 2: GitHub Plugin Configuration Dialog Box
    3. Enter the Client ID and Client Secret in the Plugin configuration dialog box.
    4. Click Apply.
  4. Restart Oxygen XML Web Author.

Result: You now have access to the Login with GitHub button in the Git Login dialog box.

Configuring a Git Integration with a GitHub Enterprise Deployment

To configure your Git integration using a GitHub Enterprise deployment, follow this procedure:
  1. Log in to GitHub Enterprise and register a new developer application. The URL is: [GithubEnterpriseUrl]/settings/applications/new.
    1. Complete the form.
    2. The Authorization callback URL field should include the following path: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/github-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
  2. Obtain the Client ID and Client Secret credentials at: [GithubEnterpriseUrl]/settings/developers.
  3. Set the Client ID, Client Secret, and the API URL in your plugin configuration by doing the following:
    1. Go to the Administration Page.

    2. In the Plugins section, click on the Configure icon for the Git plugin, select the GitHub tab, and select the Use GitHub Enterprise option.

      Figure 3: GitHub Enterprise Plugin Configuration Dialog Box
    3. Enter the API URL, Client ID, and Client Secret in the Plugin configuration dialog box. The API URL is the URL of your GitHub Enterprise deployment ([GithubEnterpriseUrl]).
    4. Click Apply.
  4. Restart Oxygen XML Web Author.
Result: You now have access to the Login with GitHub button in the Git Login dialog box.
Note: If your GitHub Enterprise deployment uses self-signed HTTPS certificates, Oxygen XML Web Author must be configured to automatically accept the security certificate.

GitLab Integration

You can configure your Git plugin to allow OAuth 2.0 authentication for GitLab integrations to access files stored in a public or private repository. You will then have access to a Login with GitLab button in the Git Login dialog box. You can configure your integration either by using a GitLab or GitLab On-Premise deployment.

Figure 4: GitLab Login Dialog Box

Configuring a Git Integration with GitLab

To configure your Git integration using GitLab, follow this procedure:
  1. Sign in or register at https://gitlab.com/profile/applications.
  2. Go to Applications and authorize Web Author to obtain the configuration parameters.
    1. The Redirect URI should be set as: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/gitlab-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
    2. For the Scopes, select: api, and read_user.
  3. Set your credentials and redirect URI in your plugin configuration by doing the following:
    1. Go to the Administration Page.

    2. In the Plugins section, click on the Configure icon for the Git plugin and select the GitLab tab.

      Figure 5: GitLab Plugin Configuration Dialog Box
    3. Enter the Application ID and Secret credentials.
    4. The Redirect URI must be set to: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/gitlab-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
    5. Click Apply.
  4. Restart Oxygen XML Web Author.

Result: You now have access to the Login with GitLab button in the Git Login dialog box.

Configuring a Git Integration with a GitLab On-Premise Deployment

To configure your Git integration using a GitLab On-Premise deployment, follow this procedure:
  1. Sign in to GitLab ([GitLabOnPremiseUrl]/profile/applications).
  2. Go to Applications and authorize Web Author to obtain the configuration parameters.
    1. The Redirect URI should be set as: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/gitlab-e-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
    2. For the Scopes, select: api, and read_user.
  3. Set your credentials, API URI, and redirect URI in your plugin configuration by doing the following:
    1. Go to the Administration Page.

    2. In the Plugins section, click on the Configure icon for the Git plugin and select the GitLab on-premise tab.

      Figure 6: GitLab On-Premise Plugin Configuration Dialog Box
    3. Enter the Application ID and Secret credentials.
    4. Set the API URI to match the location where your GitLab instance is deployed.
    5. The Redirect URI must be set to: [OXYGEN_WEBAUTHOR_URL]/plugins-dispatcher/gitlab-e-oauth/callback, where [OXYGEN_WEBAUTHOR_URL] is the location where Web Author is deployed (for example, http://Your-Domain:8077/apps/webauthor).
    6. Click Apply.
  4. Restart Oxygen XML Web Author.
Result: You now have access to the Login with GitLab button in the Git Login dialog box.
Important: Oxygen XML Web Author uses the GitLab web API to edit repositories and Git over HTTPS for actions that are not available using the web API. Therefore, your GitLab On-Premise deployment will not work with Oxygen XML Web Author if you disable Git over HTTPS in your deployment.
Note: If your GitLab On-Premise deployment uses self-signed HTTPS certificates, Oxygen XML Web Author must be configured to automatically accept the security certificate.

GitLab On-Premise Known Issues

Reverse Proxy Server in Front of GitLab On-Premise

If you have a reverse proxy in front of your GitLab On-Premise instance, make sure that requests are forwarded to the GitLab instance exactly as they are received.

A common problem occurs when using Apache as a reverse proxy in front of GitLab when it is configured to not allow encoded slashes in URLs. Apache decodes the encoded slashes and sends the malformed request to GitLab.

External URL Configured Incorrectly for GitLab On-Premise

GitLab On-Premise needs to know the URL that is used to reach it. Make sure this URL is the same as the URL written in the API URI field of the GitLab Plugin Configuration dialog box.

GitLab Submodules

You can configure your Git plugin to support GitLab submodules. To enable this support, follow these steps:
  1. Go to the Administration Page.

  2. In the Plugins section, click on the Configure icon for the Git plugin and select the Git tab.

    Figure 7: GitLab Submodule Support
  3. Select the Enable Git submodules support option.
    Note: The Disable Generic Git option can be used to remove the generic Git button from the Web Author dashboard.
  4. Click Apply.

Result: You now have access to browse or edit files from GitLab submodules.

Bitbucket Integration

You can configure your Git plugin to allow OAuth 2.0 authentication for Bitbucket integrations to access files stored in a public or private repository. You will then have access to a Login with Bitbucket button in the Git Login dialog box.

Figure 8: Bitbucket Login Dialog Box
To configure your Git integration using Bitbucket, follow this procedure:
  1. Log in to the Bitbucket and go to the user settings page ( https://bitbucket.org/account).
  2. Go to go to the OAuth page and click Add consumer to obtain the Key and Secret credentials.
  3. Set your credentials in your plugin configuration by doing the following:
    1. Go to the Administration Page.

    2. In the Plugins section, click on the Configure icon for the Git plugin and select the Bitbucket tab.

      Figure 9: Bitbucket Plugin Configuration Dialog Box
    3. Enter the Key and Secret credentials.
    4. Click Apply.
  4. Restart Oxygen XML Web Author.

Result: You now have access to the Login with Bitbucket button in the Git Login dialog box.

Custom Options for the Git Plugin

It is possible to configure a master account for the Git connector so that users do not have to login to edit documents. The following options can be set in the Oxygen XML Web Author options.xml file.
  • PLUGIN_CUSTOM_OPTIONS.git.enforced_user
  • PLUGIN_CUSTOM_OPTIONS.git.enforced_pass
  • PLUGIN_CUSTOM_OPTIONS.git.enforced_mail
Example: The options.xml file would look like this:
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_user</String>
  <String>example_username</String>
</entry>
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_pass</String>
  <String>example_password</String>
</entry>
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_mail</String>
  <String>mail@example.com</String>
</entry>