Skip to content

Commit 9af5bee

Browse files
tsusderegithub-actionssophietheking
authored
Pages custom workflow docs (#37298)
Co-authored-by: github-actions <[email protected]> Co-authored-by: Sophie <[email protected]>
1 parent c6fa875 commit 9af5bee

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎content/pages/getting-started-with-github-pages/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ topics:
1717
children:
1818
- /about-github-pages
1919
- /creating-a-github-pages-site
20+
- /using-custom-workflows-with-github-pages
2021
- /configuring-a-publishing-source-for-your-github-pages-site
2122
- /deleting-a-github-pages-site
2223
- /unpublishing-a-github-pages-site

‎content/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Using custom workflows with GitHub Pages
3+
intro: 'You can take advantage of using {% data variables.product.prodname_actions %} and {% data variables.product.prodname_pages %} by creating a workflow file or choosing from the predefined workflows.'
4+
product: '{% data reusables.gated-features.pages %}'
5+
versions:
6+
fpt: '*'
7+
ghes: '>= 3.7'
8+
ghec: '*'
9+
topics:
10+
- Pages
11+
shortTitle: Use custom workflows
12+
---
13+
14+
## About custom workflows
15+
16+
Custom workflows allow {% data variables.product.prodname_pages %} sites to be built via the use of {% data variables.product.prodname_actions %}. You can still select the branch you would like to use via the workflow file, but you are able to do much more with the use of custom workflows. To start using custom workflows you must first enable them for your current repository. For more information, see "[AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)."
17+
18+
## Configuring the `configure-pages` action
19+
20+
{% data variables.product.prodname_actions %} enables the use of {% data variables.product.prodname_pages %} through the `configure-pages` action, which also lets you gather different metadata about a website. For more information, see the [`configure-pages`](https://github.com/marketplace/actions/configure-github-pages) action.
21+
22+
To use the action place this snippet under your `jobs` in the desired workflow.
23+
24+
```yaml
25+
- name: Configure GitHub Pages
26+
uses: actions/configure-pages@v3
27+
```
28+
29+
This action helps support deployment from any static site generator to {% data variables.product.prodname_pages %}. To make this process less repetitive you can use starter workflows for some of the most widely used static site generators. For more information, see "[AUTOTITLE](/actions/using-workflows/using-starter-workflows)."
30+
31+
## Configuring the `upload-pages-artifact` action
32+
33+
The `upload-pages-artifact` actions enables you to package and upload artifacts. The {% data variables.product.prodname_pages %} artifact should be a compressed `gzip` archive containing a single `tar` file. The `tar` file must be under 10GB in size and should not contain any symbolic or hard links. For more information, see the [`upload-pages-artifact`](https://github.com/marketplace/actions/upload-github-pages-artifact) action.
34+
35+
To use the action in your current workflow place this snippet under `jobs`.
36+
37+
```yaml
38+
- name: Upload Github Pages artifact
39+
uses: actions/upload-pages-artifact@v1
40+
```
41+
42+
## Deploying {% data variables.product.prodname_pages %} artifacts
43+
44+
The `deploy-pages` action handles the necessary setup for deploying artifacts. To ensure proper functionality, the following requirements should be met:
45+
46+
- The job must have a minimum of `pages: write` and `id-token: write` permissions.
47+
- The `needs` parameter must be set to the `id` of the build step. Not setting this parameter may result in an independent deployment that continuously searches for an artifact that hasn't been created.
48+
- An `environment` must be established to enforce branch/environment protection rules. The default environment is `github-pages`.
49+
- To specify the URL of the page as an output, utilize the `url:` field.
50+
51+
For more information, see the [`deploy-pages`](https://github.com/marketplace/actions/deploy-github-pages-site) action.
52+
53+
```yaml
54+
...
55+
56+
jobs:
57+
deploy:
58+
permissions:
59+
contents: read
60+
pages: write
61+
id-token: write
62+
runs-on: ubuntu-latest
63+
needs: jekyll-build
64+
environment: github-pages
65+
url: ${{steps.deployment.outputs.page_url}}
66+
steps:
67+
- name: Deploy artifact
68+
id: deployment
69+
uses: actions/deploy-pages@v1
70+
...
71+
```
72+
73+
## Linking separate build and deploy jobs
74+
75+
You can link your `build` and `deploy` jobs in a single workflow file, eliminating the need to create two separate files to get the same result. To get started on your workflow file, under `jobs` you can define a `build` and `deploy` job to execute your jobs.
76+
77+
```yaml
78+
...
79+
80+
jobs:
81+
# Build job
82+
build:
83+
runs-on: ubuntu-latest
84+
steps:
85+
- name: Checkout
86+
uses: {% data reusables.actions.action-checkout %}
87+
- name: Setup Pages
88+
id: pages
89+
uses: actions/configure-pages@v3
90+
- name: Build with Jekyll
91+
uses: actions/jekyll-build-pages@v1
92+
with:
93+
source: ./
94+
destination: ./_site
95+
- name: Upload artifact
96+
uses: actions/upload-pages-artifact@v1
97+
98+
# Deployment job
99+
deploy:
100+
environment:
101+
name: github-pages
102+
url: ${{steps.deployment.outputs.page_url}}
103+
runs-on: ubuntu-latest
104+
needs: build
105+
steps:
106+
- name: Deploy to GitHub Pages
107+
id: deployment
108+
uses: actions/deploy-pages@v2
109+
...
110+
```
111+
112+
In certain cases, you might choose to combine everything into a single job, especially if there is no need for a build process. Consequently, you would solely focus on the deployment step.
113+
114+
```yaml
115+
...
116+
117+
jobs:
118+
# Single deploy job no building
119+
deploy:
120+
environment:
121+
name: github-pages
122+
url: ${{steps.deployment.outputs.page_url}}
123+
runs-on: ubuntu-latest
124+
steps:
125+
- name: Checkout
126+
uses: {% data reusables.actions.action-checkout %}
127+
- name: Setup Pages
128+
uses: actions/configure-pages@v3
129+
- name: Upload Artifact
130+
uses: actions/upload-pages-artifact@v3
131+
with:
132+
# upload entire directory
133+
path: '.'
134+
- name: Deploy to GitHub Pages
135+
id: deployment
136+
uses: actions/deploy-pages@v2
137+
138+
...
139+
```
140+
141+
You can define your jobs to be run on different runners, sequentially, or in parallel. For more information, see "[AUTOTITLE](/actions/using-jobs)."

0 commit comments

Comments
 (0)