Skip to main content

Gitlab Integration

Abstract

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

paligo-to-gitlab-small.png

Paligo has Continuous Integration (CI) support for Gitlab. This means you can create content in Paligo, such as a PDF or an HTML help center, and publish it to Gitlab. The content is uploaded to Gitlab as a zip file.

Note

Paligo cannot upload files that are larger than the Max Push Size limit that is set in Gitlab. You can find information on how to change the Max Push Size limit in the official Gitlab documentation.

Before you can connect Paligo to Gitlab, you need:

  • Basic Gitlab skills, including how to set up a project.

  • A Gitlab account, set up to have a personal access token (PAT). The PAT must have the api permission.

    To learn how to create a personal access key, see the official Gitlab documentation.

  • A project in your Gitlab account. The project will receive the content you publish in Paligo.

    To learn how to create a project, see the official Gitlab documentation.

You can then Connect Paligo to Gitlab and Publish Content to Gitlab.

Connect Paligo to Gitlab

To connect Paligo to Gitlab:

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

  2. Select the avatar in the top-right corner. User avatar. It shows the user's image and their name. Next to the name is a downward pointing arrow, which when selected, reveals a menu.

  3. Select Settings from the menu. Cog icon.

  4. Select the Integrations tab. Jigsaw piece icon.

    Paligo settings. The Integrations tab is highlighted.

  5. Find the Gitlab settings and select Add.

    The Add button is only shown if there are no settings currently in place. If there are settings in place, there is a Change button instead.

    Paligo displays the Gitlab integration settings.

    Gitlab integration settings in Paligo

  6. Enter the Project ID.

    This is a unique identifier that Gitlab assigns to your project. You can find it on the project's page in Gitlab.

    Close-up of project details on a Gitlab project page (in Gitlab). The project ID is shown below the project name.

  7. In Gitlab, generate a personal access token (PAT) for your user account and then copy and paste it into the Personal Access Token field in Paligo.

    To learn how to create a personal access key, see the official Gitlab documentation.

    Note

    When you create a personal access key, you can only see and copy the key when you first create it. After that, it is unavailable, so when you create it, copy and paste it into Paligo while you still have the settings open in Gitlab.

    Note

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

  8. 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 Gitlab using the settings you have provided. Paligo will detect what branches are available. Then choose the branch from the dropdown list.

    Branch field in the Paligo integrations settings. The branch button at the far right of the field is highlighted.
    Branch options shown in dropdown list. There is an option for each branch that Paligo has detected. These branches are created for the project in Gitlab.

    If you have the integration settings open, and some new branches are added in Gitlab, those new branches will not appear in the Branch field. But if you select the branch button, Paligo will update the integration settings with the latest branch information.

  9. 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, leave the Destination field empty.

  10. Use the Use non-unique file name box to control how Paligo names the output zip file. The name of the file affects how it is stored in the repository.

    If you check the box, Paligo will use the same filename for the output zip each time you publish. If the repository already contains a file of the same name, the new file will replace the old one.

    Clear the box and Paligo will add a number suffix to each output zip file when you publish. The repository will contain files for each output.

    Use non-unique file name setting. There is a checkbox and a description that explains checking the box will result in the same file name being used for each upload.

  11. Select Save.

  12. Select the Change button for the Gitlab integration.

  13. 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 Gitlab repository.

Publish Content to Gitlab

To publish from Paligo directly to Gitlab, you need:

  • A publication or topic (ready to publish) in Paligo

  • A suitable layout for publishing, for example, an HTML5 help center layout (see Create a Layout)

  • The Paligo-to-Gitlab integration settings in place (see Connect Paligo to Gitlab).

With these in place, you can publish your content in Paligo and it will be uploaded to a Gitlab repository automatically.

  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 Filtering / Profiling and Variables to learn how to use these features.

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

    upload-to-gitlab.png

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

    gitlab-edit-branch-directory.png

    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 uploaded to your chosen repository branch and folder in Gitlab.