hosting-on-github.md (5682B)
1 ---
2 title: Host on GitHub
3 linktitle: Host on GitHub
4 description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Action Workflow
5 date: 2014-03-21
6 publishdate: 2014-03-21
7 categories: [hosting and deployment]
8 keywords: [github,git,deployment,hosting]
9 authors: [Spencer Lyon, Gunnar Morling]
10 menu:
11 docs:
12 parent: "hosting-and-deployment"
13 weight: 30
14 weight: 30
15 sections_weight: 30
16 toc: true
17 aliases: [/tutorials/github-pages-blog/]
18 ---
19
20 GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][] and automating development workflows and build with [GitHub Actions].
21
22 ## Assumptions
23
24 1. You have Git 2.8 or greater [installed on your machine][installgit].
25 2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
26 3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
27
28 ## Types of GitHub Pages
29
30 There are two types of GitHub Pages:
31
32 - User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
33 - Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
34
35 Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use.
36
37 ## Branches for GitHub Actions
38
39 The GitHub Actions used in these instructions pull source content from the `main` branch and then commit the generated content to the `gh-pages` branch. This applies regardless of what type of GitHub Pages you are using. This is a clean setup as your Hugo files are stored in one branch and your generated files are published into a separate branch.
40
41 ## GitHub User or Organization Pages
42
43 As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
44
45 1. You must create a repository named `<USERNAME>.github.io` or `<ORGANIZATION>.github.io` to host your pages
46 2. By default, content from the `main` branch is used to publish GitHub Pages - rather than the `gh-pages` branch which is the default for project sites. However, the GitHub Actions in these instructions publish to the `gh-pages` branch. Therefore, if you are publishing Github pages for a user or organization, you will need to change the publishing branch to `gh-pages`. See the instructions later in this document.
47
48 ## Build Hugo With GitHub Action
49
50 GitHub executes your software development workflows. Everytime you push your code on the Github repository, Github Actions will build the site automatically.
51
52 Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on [actions-hugo](https://github.com/marketplace/actions/hugo-setup)):
53
54 ```yml
55 name: github pages
56
57 on:
58 push:
59 branches:
60 - main # Set a branch to deploy
61 pull_request:
62
63 jobs:
64 deploy:
65 runs-on: ubuntu-20.04
66 steps:
67 - uses: actions/checkout@v2
68 with:
69 submodules: true # Fetch Hugo themes (true OR recursive)
70 fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
71
72 - name: Setup Hugo
73 uses: peaceiris/actions-hugo@v2
74 with:
75 hugo-version: 'latest'
76 # extended: true
77
78 - name: Build
79 run: hugo --minify
80
81 - name: Deploy
82 uses: peaceiris/actions-gh-pages@v3
83 if: github.ref == 'refs/heads/main'
84 with:
85 github_token: ${{ secrets.GITHUB_TOKEN }}
86 publish_dir: ./public
87 ```
88
89 For more advanced settings [actions-hugo](https://github.com/marketplace/actions/hugo-setup) and [actions-gh-pages](https://github.com/marketplace/actions/github-pages-action).
90
91 ## Github pages setting
92 By default, the GitHub action pushes the generated content to the `gh-pages` branch. This means GitHub has to serve your `gh-pages` branch as a GitHub Pages branch. You can change this setting by going to Settings > GitHub Pages, and change the source branch to `gh-pages`.
93
94 ## Change baseURL in config.toml
95 Don't forget to rename your `baseURL` in `config.toml` with the value `https://<USERNAME>.github.io` for your user repository or `https://<USERNAME>.github.io/<REPOSITORY_NAME>` for a project repository.
96
97 Unless this is present in your `config.toml`, your website won't work.
98
99 ## Use a Custom Domain
100
101 If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirement of GitHub Pages.
102
103 Refer to the [official documentation for custom domains][domains] for further information.
104
105 [config]: /getting-started/configuration/
106 [domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
107 [ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
108 [ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/
109 [ghsignup]: https://github.com/join
110 [GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
111 [installgit]: https://git-scm.com/downloads
112 [orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checkout.txt---orphanltnewbranchgt
113 [Quick Start]: /getting-started/quick-start/
114 [submodule]: https://github.com/blog/2104-working-with-submodules
115 [worktree feature]: https://git-scm.com/docs/git-worktree
116 [GitHub Actions]: https://docs.github.com/en/actions