GitHub Integration

Abstract

You can upload content directly from Paligo to GitHub. Set up the Paligo to GitHub integration so that Paligo can connect to GitHub, and then you can publish.

paligo-to-github-small.jpg

Paligo has Continuous Integration (CI) support for GitHub. This means you can create content in Paligo, such as PDFs or an HTML help center, and publish it to GitHub. When the content is uploaded to GitHub, you can unzip it (automatically if you so choose) to make it instantly available live to your end users.

Note

GitHub has a size limit for file uploads, and so is not a good fit for larger documentation projects, as any files above this limit are blocked. GitHub documentation states that the limit is 100MB , but for Paligo the limit is 67MB as the content has to be encoded and compressed. Other systems, such as BitBucket, do not have the size limit for uploads.

Before you can publish from Paligo to GitHub, you need:

  • A GitHub account

  • Basic GitHub knowledge and skills, including how to create a repository

  • A repository in GitHub. Paligo will upload published output to the repository. The output is uploaded as a zip file.

To set up Paligo to publish to GitHub:

This will allow Paligo to publish your output as a zip file to your chosen repository. In GitHub, you can use a web hook to automate the unzipping of the file, so that you can use the content.

To set up Paligo to connect to GitHub, you need to have:

  • A GitHub account.

  • Access to the repository where you want to upload/publish content from Paligo.

  • Repository owner username.

    If there are multiple users, the repository owner may not be the same user as the GitHub account.

  • A personal access token for the repository. This can be for the user account of the owner of the repository or a developer who has access. The token must have the following permissions:

    • repo:status

    • repo_deployment

    • public_repo

    • repo:invite

    • security_events

    • write:packages

    To find out how to create a personal access token, see the official GitHub help page.

To connect Paligo to GitHub:

  1. Log in to Paligo via a user account that has administrator permissions.

  2. Select your profile name in the upper right corner to display a menu, and then select Settings.

  3. In the Settings view, select the Integrations tab.

  4. Find the GitHub settings and select Add.

    Note

    Add is only available the first time you set up an integration. After that, Add is replaced by Change.

    Paligo displays the GitHub integration settings.

    GitHub integration settings in Paligo.
  5. Enter the Username for an owner of the GitHub repository.

  6. Enter the Personal Access Token.

    The personal access token can be for any user account that can access the repository. But it must have the required permissions.

  7. Enter the Repository Owner. Leave this empty if the owner is the same as the Username.

    Typically, if there is only one user account, the repository owner is the same as the Username. But it is possible to have multiple users (developers), in which case, the Username and Repository Owner could be different user accounts.

  8. Enter the Repository Name. This has to match the name given to the repository in GitHub.

  9. Choose the Branch that Paligo will upload content to. The first time you set up the integration, select the branch button, so that Paligo can connect to GitHub using the settings you have provided. Paligo will detect what branches are available. Then choose the branch from the dropdown list.

    The branch field in the integration settings. The branch button on the right of the field is highlighted.

    Paligo does not automatically update the integration settings page while it is open. This means that if you have the integration settings page open, and some new branches are added in GitHub, those new branches will not appear in the Branch field. But if you select the branch button, Paligo will update the settings page with the latest branch information.

  10. In the Destination folder field, enter the directory path for the folder that you want Paligo to upload the zip file to. This folder is inside the repository.

    For example:

    Folder 1/Folder 2/

    To upload the zip file directly to the root of the bucket, leave the Destination field empty.

  11. Check the Use non-unique file name box if you want Paligo to use a consistent file name for the zip file. Each time Paligo publishes content via the integration, the zip file name will be the same.

    If you want Paligo to generate different names for the zip file each time, clear the checkbox.

  12. Select Save.

  13. Select the Change button for the GitHub integration.

  14. Select Test Settings to run a connection test. If the settings are correct, Paligo will show a green success notification.

    If the connection test fails, Paligo shows a red failure notification. Check each connection setting carefully, to make sure you have not made any mistakes and try again. If the connection test continues to fail, contact Paligo support for assistance.

When the connection is made, you can publish content from Paligo to a GitHub repository.

You can publish content from Paligo to GitHub, and the process is very similar to "regular" publishing. You create your publication and topics, and set up a layout for the type of output you want, such as PDF, HTML5, etc. Then you choose the publication settings and Paligo creates a zip file that contains your output content. The zip file is downloaded in your browser and it is also uploaded to your chosen GitHub repository.

Note

You can use a GitHub webhook to automatically unzip the contents.

To publish to GitHub, the integration settings need to be in place so that Paligo can connect to GitHub and knows which branch and directory to publish to. You will also need to have a publication and layout set up to create the output you want, for example, an HTML5 help center. With these in place, you can publish from Paligo to GitHub:

  1. In Paligo, select the options menu ( ... ) for the publication that you want to publish, and then select Publish.

    Publish document dialog showing settings for different output types, languages, profiling attributes, variables, and upload output.
  2. On the Publish document dialog, select the type of output you want, for example, HTML5.

  3. Choose the layout that you want to use for publishing. The settings in the layout are applied when Paligo generates the output.

  4. Choose the Languages to publish to. If you do not have any translations, you can only select the original/source language.

  5. If you have set filters (Profiling attributes) on topics or elements, and/or have used variables, choose which values to use for the publication. See Filters (Profiling) and Variables to learn how to use these features.

  6. In the Upload output section, check the Upload to GitHub box. By default, Paligo will upload the output to the repository and folder that are specified in the Paligo to GitHub integration settings.

    Upload output settings. There are settings for Upload to Github, Upload via FTP, Upload to Bitbucket, and Upload to AWS S3. Upload to Github is selected.

    You can publish to a different branch and/or folder if required. Select the Edit icon next to Upload to GitHub, and then select the branch and/or folder on the Edit dialog.

    GitHub dialog for changing the branch and/or destination folder for a single publish.

    The settings you choose will only be used for this individual publishing process. Any future publishing will revert back to using the branch and folder that are defined in the integration settings.

  7. Select Publish document.

    Paligo generates the output, applying the settings from the layout and the Publication document dialog in the process. When the output is created, it is downloaded in your browser as a zip file. The zip file is also uploaded to your chosen repository branch and folder in GitHub.

    In GitHub, you can use a web hook to automate the unzipping of the file, so that it is published live to end users.