Configuring GitHub
Configuring your site in GitHub
Now that you’ve configured your site locally, commit these changes to GitHub.
GitHub kicks off a build and deploy action for your site. This action may fail; this is okay because we still need to do a little more setup first.
Hosting your site in GitHub Pages
By default, jhDocs sites are hosted by GitHub, directly out of your GitHub repo, using GitHub Pages.
Sites hosted in GitHub Pages are either public or restricted to members of the repo. If you need your doc site to be restricted to, say, logged-in users, you will need to find a different hosting solution that allows you to do that. Hosting outside of GitHub Pages is beyond the scope of jhDocs and is left up to the wisdom of any team who needs a more complex hosting solution.
The rest of this section assumes that you’re hosting your jhDocs site in GitHub Pages as a publicly accessible website.
We’ll configure your GitHub Pages setup here next.
In your GitHub repo, click the Settings tab in the top-middle area of the screen. Then click the Pages tab in the middle-left area of the screen.
At this point, GitHub Pages has not been configured yet. In the screenshot below, you can see that the Branch dropdown is set to a value of None.
In the Branch dropdown, select the gh-pages option. The build and deploy script generates your site into a gh-pages branch, which it then deploys as your live site.
At this point, GitHub will calculate a strange looking URL for your GitHub Pages site. This is because – by default – your GitHub pages are not visible to the public. GitHub creates an internal hosting site that uses that goofy URL.
Let’s fix this, because this is typically not what we want. Private GitHub Pages sites are only visible to the people who are part of the repo.
We want our GitHub Pages sites to be publicly accessible. Now that GitHub Pages has been turned on, you should now see a new “Github Pages visibility” section in the page. Click the dropdown and select the Public option. GitHub will require you to confirm this change by asking you to manually type in the repo name to ensure that you know that you’re making the site publicly available.
After this change, GitHub should re-run the build and deploy action, which should publish your site to GitHub Pages using an expected URL, open to the public.
You might be concerned that your new site is publicly accessible now, before you’ve set up all of your content. The odds are that the doc site you’re building will use a new URL that hasn’t been used before, so you typically shouldn’t worry about publishing the site publicly at this stage. No one knows about the site URL until you tell them.
You’ll typically share this URL with stakeholders on your own team as you develop the doc site, so they can see the progress and provide feedback.
And of course, you’ll share the URL with your wider audience when you’re ready to take your new documentation site live.
Configuring branch protection
It’s generally a good idea to create a branch protection rule for at least the main branch in your repo. A branch protection rule can help you protect your main branch from direct commits, specifying a pull request process, if that’s appropriate for your team.
Learn more about GitHub branch protection here.
Adding other users to your repo
Once you have all team members who will be contributing to the repo added both to (a) Jack Henry GitHub and (b) the specific organization within Jack Henry GitHub, you’ll want to add those team members to the repo with the appropriate permissions.
Learn more about managing the people and teams who will contribute to your repo here.
Next topic: Configuring AI Assist