Skip to main content

GitHub-Integration

Zusammenfassung

Sie können Inhalte direkt aus Paligo zu GitHub hochladen. Richten Sie die Paligo-to-GitHub-Integration so ein, dass Paligo eine Verbindung zu GitHub herstellen kann. Anschließend können Sie die Veröffentlichung ausführen.

paligo-to-github-small.jpg

Paligo unterstützt Continuous Integration (CI) für GitHub. Das bedeutet, dass Sie Inhalte in Paligo erstellen können, wie PDFs oder ein HTML-Helpcenter, und zu GitHub veröffentlichen können. Wenn die Inhalte zu GitHub hochgeladen werden, können Sie diese entpacken (automatisch, wenn Sie dies wünschen), um sie sofort live für Ihre Endbenutzer bereitzustellen.

Anmerkung

GitHub hat eine Größengrenze für Dateiuploads. Daher eignet sich GitHub nicht für größere Dokumentationsprojekte, da Dateien oberhalb dieser Grenze blockiert werden. In der GitHub-Dokumentation ist angegeben, dass das Limit 100 MB beträgt. Für Paligo beträgt das Limit jedoch 67 MB, da der Inhalt kodiert und komprimiert werden muss. Andere Systeme, z. B. BitBucket, haben keine Größenbeschränkung für Uploads.

Bevor Sie von Paligo zu GitHub veröffentlichen können, benötigen Sie Folgendes:

  • Ein GitHub-Konto

  • GitHub-Basiskenntnisse und -fähigkeiten einschließlich in Bezug auf die Erstellung eines Repositorys

  • Ein Repository in GitHub. Paligo lädt die veröffentlichte Ausgabe zum Repository hoch. Die Ausgabe wird als ZIP-Datei hochgeladen.

So richten Sie Paligo für die Veröffentlichung zu GitHub ein:

  1. Verbinden von Paligo mit GitHub.

  2. In GitHub veröffentlichen.

So kann Paligo Ihre Ausgabe als ZIP-Datei zu dem von Ihnen gewählten Repository veröffentlichen. In GitHub können Sie einen Webhook verwenden, um das Entpacken der Datei zu automatisieren, damit Sie den Inhalt verwenden können.

Verbinden von Paligo mit GitHub

Um Paligo für die Verbindung mit GitHub einzurichten, benötigen Sie Folgendes:

  • Ein GitHub-Konto.

  • Zugriff auf das Repository, zu dem Sie Inhalte aus Paligo hochladen/veröffentlichen möchten.

  • Benutzername des Repository-Besitzers.

    Wenn es mehrere Benutzer gibt, darf der Repository-Besitzer nicht der Benutzer für das GitHub-Konto sein.

  • Ein persönliches Zugriffs-Token für das Repository. Dies kann ein Token für das Benutzerkonto des Repository-Besitzers oder eines Entwicklers sein, der Zugriff hat. Das Token muss folgende Berechtigungen haben:

    • repo:status

    • repo_deployment

    • public_repo

    • repo:invite

    • security_events

    • write:packages

    Informationen zum Erstellen eines persönlichen Zugriffs-Tokens finden Sie auf der offiziellen GitHub-Hilfeseite.

So verbinden Sie Paligo mit GitHub:

  1. Melden Sie sich bei Paligo über ein Benutzerkonto mit Administratorberechtigungen an.

  2. Melden Sie sich bei Paligo über ein Benutzerkonto mit Administratorberechtigungen an.

  3. Wählen Sie den Avatar in der oberen rechten Ecke aus. 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.

  4. Wählen Sie im Menü Einstellungen aus. Cog icon.

  5. Wählen Sie die Registerkarte Integrationen. Jigsaw piece icon.

    Paligo settings. The Integrations tab is highlighted.

  6. Wählen Sie im Feld GitHub Hinzufügen aus (bzw. Ändern, wenn bereits eine Integration eingerichtet wurde).

    Add_Github.png

  7. Geben Sie den Repository-Besitzer ein. Lassen Sie das Feld leer, wenn der Besitzer mit dem Benutzernamen identisch ist.

    Wenn es nur ein einziges Benutzerkonto gibt, ist der Repository-Besitzer in der Regel derselbe wie der Benutzername. Es ist jedoch möglich, mehrere Benutzer (Entwickler) zu haben. In diesem Fall könnten Benutzername und Repository-Besitzer unterschiedliche Benutzerkonten sein.

    GitHub integration settings in Paligo.

  8. Geben Sie den Benutzernamen für das GitHub-Repositorys ein.

  9. Erstellen Sie in GitHub ein persönliches Zugriffs-Token (PAT) für Ihr Benutzerkonto, siehe offizielle GitHub-Dokumentation.

    Anmerkung

    Das persönliche Zugriffs-Token kann für jedes Benutzerkonto erstellt werden, das auf das Repository zugreifen kann, es muss jedoch über die API-Berechtigung verfügen.

  10. Kopieren Sie es und fügen Sie es in das Feld Persönliches Zugriffs-Token in Paligo ein.

  11. Geben Sie den Repository-Namen ein. Dieser muss mit dem Namen des Repositorys in GitHub übereinstimmen.

  12. Wählen Sie die Verzweigung aus, in die Paligo Inhalte hochladen soll.

    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.

    Wenn das Feld „Verzweigung“ leer ist (oder wenn eine Verzweigung fehlt), wählen Sie die Schaltfläche „Verzweigung“, um die Verzweigungen zu laden. Wählen Sie dann den Zweig aus der Dropdown-Liste aus.

    Branch field in the Paligo integrations settings. The branch button at the far right of the field is highlighted.

    Anmerkung

    Wenn die Integrationseinstellung beim Hinzufügen neuer Verzweigungen geöffnet ist, erscheinen diese neuen Verzweigungen nicht im Feld Verzweigung, es sei denn, die Einstellung wird neu geladen.

    Wählen Sie die Schaltfläche „Verzweigung“ aus, um die Integrationseinstellungen mit den neuesten Zweiginformationen zu aktualisieren.

  13. Geben Sie als Zielordner den Verzeichnispfad für den Ordner ein, in den Paligo Inhalte hochladen soll.

    Wenn Sie die Zip-Datei direkt in das Stammverzeichnis hochladen möchten, lassen Sie dieses Feld unausgefüllt.

    Destination_Folder.png

  14. Legen Sie mithilfe von Einen nicht eindeutigen Dateinamen verwenden fest, wie Paligo die Zip-Datei der Ausgabe benennen soll. Damit wird gesteuert, wie die Datei im Repository gespeichert wird.

    • Aktivieren Sie das Kontrollkästchen, um bei jeder Veröffentlichung einen einheitlichen Dateinamen für die Ausgabe-Zip-Datei zu verwenden. Enthält das Repository bereits eine Datei mit demselben Namen, wird die alte Datei mit der neuen überschrieben.

    • Deaktivieren Sie das Kontrollkästchen, um bei der Veröffentlichung jeder Ausgabe-Zip-Datei ein Nummernsuffix hinzuzufügen. Das Repository enthält Dateien für jede Ausgabe.

    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.

  15. Prüfen Sie mit Für die Verbindung zu Gitlab das von Paligo bereitgestellte Gateway verwenden, ob das bereitgestellte Gateway verwendet wird:

    • Aktivieren Sie das Kontrollkästchen, um das bereitgestellte Gateway zu verwenden.

    • Deaktivieren Sie das Kontrollkästchen, um es nicht zu verwenden.

    Github_Provided_Gateway_small.jpg

  16. Drücken Sie Speichern.

  17. Wählen Sie die Schaltfläche Ändern für die Integration aus.

  18. Wählen Sie Testeinstellungen aus, um einen Verbindungstest durchzuführen.

    Test_Reset_Settings_Integrations_small.jpg

  19. Lautet Ihre Einstellung:

    • Richtig, zeigt Paligo eine grüne Erfolgsmeldung an.

    • Falsch, zeigt Paligo eine rote Fehlermeldung an.

      Überprüfen Sie jede Verbindungseinstellung sorgfältig, um sicherzustellen, dass Sie keine Fehler gemacht haben, und versuchen Sie es erneut.

      Wenn der Verbindungstest weiterhin fehlschlägt, wenden Sie sich an den Paligo-Support, um Unterstützung zu erhalten.

Wenn die Verbindung hergestellt ist, können Sie In GitHub veröffentlichen.

In GitHub veröffentlichen

Sie können Inhalte aus Paligo zu GitHub veröffentlichen. Der Prozess ist der „regulären“ Veröffentlichung sehr ähnlich. Sie erstellen Ihre Publikation und Ihre Topics und richten dann ein Layout für den gewünschten Ausgabetyp ein, z. B. PDF, HTML5 usw. Anschließend wählen Sie die Veröffentlichungseinstellungen aus. Paligo erstellt dann eine Zip-Datei mit den Ausgabeinhalten. Die Zip-Datei wird in Ihren Browser heruntergeladen und auch in das von Ihnen gewählte GitHub-Repository hochgeladen.

Anmerkung

Sie können einen GitHub-Webhook verwenden, um den Inhalt automatisch zu entpacken.

Um zu GitHub zu veröffentlichen, müssen die Integrationseinstellungen eingerichtet sein, damit Paligo eine Verbindung zu GitHub herstellen kann und weiß, in welchem Zweig und Verzeichnis veröffentlicht werden soll. Sie müssen auch eine Publikation und ein Layout einrichten, um die gewünschte Ausgabe zu erstellen, z. B. ein HTML5-Helpcenter. Jetzt können Sie von Paligo zu Github veröffentlichen:

  1. Wählen Sie das gepunktete Menü (...) für das Topic oder die Publikation im Content Manager aus.

    selectpublish.png

  2. Wählen Sie Veröffentlichen aus. Download icon.

    publish-document-jan23.png

    Paligo zeigt das Dialogfeld Dokument veröffentlichen an.

  3. Wählen Sie den Ausgabetyp, den Sie veröffentlichen möchten (z. B. PDF, HTML, HTML5, Word, XML, eLearning, SCORM usw.).

  4. Wählen Sie das Layout, das für Ihre Ausgabe verwendet werden soll.

  5. Wählen Sie die zu veröffentlichenden Sprachversionen aus.

    Languages section of Publish document dialog. There are options for each language. English UK and Swedish are selected.

    Anmerkung

    Wenn keine Übersetzungen verfügbar sind, wird nur die Ausgangssprache angezeigt. Bei mehreren genehmigten Übersetzungen in verschiedene Sprachen können Sie auswählen, welche Sie mit aufnehmen möchten. Paligo veröffentlicht jede Sprachversion als separate Ausgabe.

    Bei der PDF-Ausgabe können Sie sie als eine einzige, mehrsprachige Publikation veröffentlichen; aktivieren Sie hierzu das Kontrollkästchen Ausgewählte Sprachen kombinieren.

  6. [en] If your content is set up to use Filterung/Profiling, use the Profiling attributes section to apply them. [Optional]. If you do not use filtering, ignore this setting.

    [en] Select Edit and then choose the value for each filter that you want Paligo to use. For example, for Audience, choose Expert to include content that is marked as for expert users.

    Wenn Sie keinen Filter anwenden möchten, lassen Sie das Feld leer.

    Profiling attributes dialog. Outputformat is set to include HTML.

    Wählen Sie OK aus, um das/die gewählte(n) Profiling-Attribut(e) hinzuzufügen.

    Profiling attributes section of Publish document dialog. Shows Outputformat: HTML selected.

  8. Aktivieren Sie im Abschnitt Upload-Ausgabe das Kontrollkästchen Zu GitHub hochladen. Standardmäßig lädt Paligo die Ausgabe zu dem Repository und Ordner hoch, das/der in den Einstellungen für die Paligo-to-GitHub-Integration angegeben sind.

    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.

    Sie können auch zu einem anderen Zweig und/oder Ordner veröffentlichen, wenn erforderlich. Wählen Sie das Symbol Bearbeiten neben Zu GitHub hochladen und dann den Zweig und/oder Ordner im Dialogfeld „Bearbeiten“ aus. Die von Ihnen ausgewählten Einstellungen werden nur für diesen einzelnen Veröffentlichungsprozess verwendet. Bei jeder zukünftigen Veröffentlichung werden die in den Integrationseinstellungen definierten Zweige und Ordner wiederverwendet.

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

  9. Im Abschnitt Ausgabedateiname können Sie den Dateinamen verwalten.

    Standardmäßig verwendet Paligo die in den Systemeinstellungen festgelegte Dateinamensyntax.

    Output filename section. There is a Template field that contains the values ID, Title, and Format. In the top-right corner is a preview of the filename that Paligo will generate if the current settings are used.

    Um die im Dateinamen enthaltenen Angaben zu ändern, geben Sie Ihr gewünschtes Format in den Publikationseinstellungen ein. Die Standardeinstellung lautet: ID-Title-Format.

    Sie können folgende Angaben in den Namen aufnehmen:

    • ID - Die ID des Dokuments.

    • Titel - Der Titel der Publikation oder des Topics, das Sie veröffentlichen.

    • Format - Der Name des Ausgabeformats, zum Beispiel PDF oder HTML5.

    • Bearbeitungsdatum - Das Datum, an dem die Publikation oder das Topic zuletzt bearbeitet wurde.

    • Label der Verzweigung – Der Text aus dem Label der Verzweigung für die Publikation oder das Topic. Dies gilt nur, wenn Ihre Inhalte verzweigt wurden und die Verzweigung über ein Label verfügt. Details hierzu finden Sie unter Beschriftungen für Zweige hinzufügen oder bearbeiten.

    • Eindeutiger Wert - Eine von Paligo generierte zufällige Zeichenfolge, die dem Dateinamen hinzugefügt wird, um ihn einzigartig zu machen. Dadurch kann verhindert werden, dass die Datei durch spätere Veröffentlichungen desselben Dokuments überschrieben wird.

    Tipp

    Wenn Sie @ in das Feld eingeben, zeigt Paligo eine Liste der verfügbaren Werte an, aus denen Sie wählen können. Um einen Wert zu entfernen, klicken Sie ihn an und verwenden Sie die Löschtaste oder Rücktaste, um alle Zeichen zu entfernen.

    Anmerkung

    Der in der oberen rechten Ecke angezeigte Dateiname ist eine Vorschau auf den Dateinamen, den Paligo bei der Veröffentlichung verwendet.

  10. Legen Sie die optionalen Parameter fest (lassen Sie das Kontrollkästchen deaktiviert, wenn Sie diese Funktionen nicht wünschen):

    • Speichern Sie die Ausgabe in Paligo - Aktivieren Sie das Kontrollkästchen, um die Zip-Datei in der Ressourcenübersicht zu speichern. Deaktivieren Sie das Kontrollkästchen, wenn Paligo nur die veröffentlichte Ausgabedatei in Ihrem Browser herunterladen soll.

    • E-Mail an mich - Aktivieren Sie dieses Kontrollkästchen, wenn Paligo Ihnen eine E-Mail schicken soll, wenn die Publikation bereit ist. Dies ist bei sehr großen Publikationen von Vorteil, deren Verarbeitung und Veröffentlichung länger dauern können.

    • Debug-Build erstellen - Aktivieren Sie dieses Kontrollkästchen, wenn Paligo eine Protokolldatei und einen Link-Bericht einfügen soll. Wenn Ihre Inhalte ein Problem verursachen, kann der Paligo Support Sie bitten, diese Funktion zu aktivieren, damit er die Protokolldateien zur Ermittlung der Ursache nutzen kann.

  11. Wählen Sie Dokument veröffentlichen aus.

    Paligo beginnt mit der Verarbeitung Ihrer Inhalte und wendet Ihre Layout- und Publikationseinstellungen an. Die benötigte Zeit ist von dem Umfang der Inhalte abhängig, die Sie veröffentlichen (je mehr Inhalte, desto länger dauert der Vorgang).

    Publish_Progress_Bar_small.jpg

    Ein Fortschrittsbalken zeigt Ihnen an, wie viel der Verarbeitung Paligo bereits abgeschlossen hat und wie viel noch zu tun ist. Wenn die Verarbeitung abgeschlossen ist, wird eine Benachrichtigung angezeigt.

    Die veröffentlichte Ausgabe erscheint wie folgt:

    • Eine Zip-Datei mit der veröffentlichten Ausgabe erscheint im Ordner Downloads auf Ihrem Computer.

      Wenn Sie die Einstellungen Ihres Browsers geändert haben, um heruntergeladene Dateien an einem anderen Ort zu speichern, befindet sich die Zip-Datei stattdessen dort.

      Wenn Sie eine Publishing-Integration verwenden, wird die Zip-Datei auch an den entsprechenden Dienst gesendet.

    • Ein Link im Panel Aktivitätsfeed zum Herunterladen der veröffentlichten Inhalte.

    Anmerkung

    Um die Inhalte online zur Verfügung zu stellen, entpacken Sie zunächst die Datei. Sie können die Datei dann lokal verwenden oder einen FTP-Client wie Filezilla verwenden, um den entpackten Inhalt auf einen Webserver hochzuladen.

    Tipp

    Sie können Ihre Publikationseinstellungen speichern und wiederverwenden, um einen reibungsloseren Publikationsprozess zu erreichen, siehe Publikationseinstellungen. Alle gespeicherten Einstellungen können auch für [en] Batch Publishing verwendet werden.

    Publish document dialog has a Save Settings option and a Saved Settings tab. The option saves the currently shown settings and these can then be selected in a single action on the tab.

In GitHub können Sie einen Webhook verwenden, um das Entpacken der Datei zu automatisieren, sodass sie live für Endbenutzer veröffentlicht wird.