Installing a theme from a private Git repository

Documentation Site Management
, ,
1

:bookmark: This guide explains how to install a Discourse theme or theme component from a private GitHub repository.

:person_raising_hand: Required user level: Administrator

Summary

This documentation covers the process of installing a Discourse theme or theme component from a private GitHub repository. It includes steps for generating and using SSH keys for secure access. You will need to have administrator access to both your Discourse instance and the GitHub repository you are installing. This is how you can use your own private themes and theme components on your forum.

Prerequisites

Before you begin, ensure you have:

  • Administrator access to your Discourse instance
  • A private Git repository containing your theme or component
  • Access to add deploy keys to your Git repository (admin/owner level)

Step-by-step guide

  1. Go to your private GitHub repository and copy the SSH address from the Clone SSH tab.

Screenshot 2024-09-13 at 6.36.50 PM
Screenshot 2024-09-13 at 6.36.50 PM778×702 37 KB


2. Navigate to your Discourse admin panel.

3. In the admin sidebar, go to Appearance - Themes or Component, (depending on which you are installing). If you are using the older style admin navigation bar - go to Customize - Themes or Components.

4. Click on Install and then select From a git repository.

The image shows a graphical user interface with a dark theme, displaying an installation dialog for a repository containing theme. (Captioned by AI)
The image shows a graphical user interface with a dark theme, displaying an installation dialog for a repository containing theme. (Captioned by AI)1114×644 33.2 KB


5. Paste the SSH address you copied from the private repository in step 1. It should be in the format: git@github.com:USERNAME/REPO-NAME.git.

:warning: Make sure to use the clone with SSH link, not the one that starts with https


6. An SSH key is automatically generated and displayed in a new text box.

Screenshot 2024-09-13 at 6.37.57 PM
Screenshot 2024-09-13 at 6.37.57 PM1126×1062 96 KB


7. Click the copy icon in the top right corner of that box to copy the new SSH key. Do not click install or close this modal yet.

8. Now go to your private GitHub repository settings (e.g., on GitHub, go to Settings > Deploy keys)

Screenshot 2024-09-13 at 6.43.12 PM
Screenshot 2024-09-13 at 6.43.12 PM1776×1122 81.4 KB


9. Add a new deploy key. You will have to give it an appropriate title. Paste the SSH key you copied from Discourse into the deploy key field.

This image shows a computer screen displaying a user interface for adding new deployment keys. (Captioned by AI)
This image shows a computer screen displaying a user interface for adding new deployment keys. (Captioned by AI)1160×914 98.8 KB


10. Click Add key to save the deploy key in your Git repository settings.

The image shows a screenshot of a computer interface with the title "Deploy keys" and an option to add more keys. (Captioned by AI)
The image shows a screenshot of a computer interface with the title "Deploy keys" and an option to add more keys. (Captioned by AI)1160×370 28.4 KB


11. Return to the Discourse theme installation modal and click the Install button. You should now see your new theme or component settings page.

Screenshot 2024-09-13 at 6.39.18 PM
Screenshot 2024-09-13 at 6.39.18 PM1410×1126 79.2 KB

Best practices

  • Always use the SSH URL for your repository, not the HTTPS URL.
  • Keep your deploy keys secure and don’t share them publicly. If possible, store them in a password vault application.
  • Regularly update your theme or components to ensure you have the latest features and security updates.

FAQs

Q: Can I use this method with Git providers other than GitHub?
A: Yes, this method should work with any Git provider that supports deploy keys or SSH authentication.

Q: Will Discourse remember the SSH key for future updates?
A: Yes, Discourse will store the generated private key and use it for future access to the Git repository.

Q: Can I change the private repository later?
A: Yes, you can update the repository URL in the theme settings if needed.

Additional resources

*SSH keys used in this topic were only generated for this documentation

Last edited by @Lilly 2024-09-15T13:00:04Z

Last checked by @Lilly 2024-09-14T01:10:27Z

Check documentPerform check on document:
33 Likes