Skip to content

Commit ce5a8bc

Browse files
starkris51starkris51
committed
Add GitHub Action and release workflow for documentation deployment
1 parent 1521470 commit ce5a8bc

File tree

3 files changed

+266
-0
lines changed

3 files changed

+266
-0
lines changed

‎README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,58 @@
11
# bcc-developer-docs-deploy
2+
3+
## Updating the GitHub Action
4+
5+
The `action.yml` file is a [composite](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) GitHub Action. It is used by workflows in other repositories like this:
6+
7+
## Updating the GitHub Action
8+
9+
The `action.yml` file is a [composite](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) GitHub Action. It is used by workflows in other repositories like this:
10+
11+
```yml
12+
steps:
13+
- name: Build documentation site
14+
uses: bcc-code/bcc-developer-docs-deploy@v1
15+
with:
16+
title: Documentation Guide
17+
description: Information on how to set up documentation for BCC projects
18+
```
19+
20+
You can see a full workflow in action [in this repository](./.github/workflows/build-and-deploy-documentation.yml), as it is used here as well to build the documentation.
21+
22+
The "version" of the Action (the `@v1` part) is just a tag that is added to a commit on this repository. When updating the `action.yml` file, there are two ways to propagate this update to all the other repositories.
23+
24+
### 1. Create a new tag
25+
26+
This is the easiest approach. Use this if there are any breaking changes to the action, such as renaming an argument. Create a new tag with a comment like this:
27+
28+
```sh
29+
git tag -a -m "Action: Add argument" v2
30+
```
31+
32+
This creates a `v2` tag with a comment of `Action: Add argument`.
33+
34+
Then push the tag to GitHub (and any non-pushed commits) by appending the `follow-tags` flag to `git push`:
35+
36+
```sh
37+
git push --follow-tags
38+
```
39+
40+
After doing this, all the workflows in this and other repositories need to be updated to use that `v2` tag. This enables gradual adoption, but the downside is of course a potential burden of having to upgrade a lot of repositories.
41+
42+
### 2. Republish an existing tag
43+
44+
By deleting and republishing the last tag, any future workflow will use the updated version without having to update all the other workflows. This is a **dangerous** action though, as an error in the configuration can lead to all repositories breaking, and you're deleting the tag from the server forever. **Only use this for backwards compatible changes**.
45+
46+
First delete the tag locally:
47+
48+
```sh
49+
git tag -d v1
50+
```
51+
52+
Then delete it on GitHub:
53+
54+
```sh
55+
git push --delete origin v1
56+
```
57+
58+
The run the two commands under option 1 to create and push this tag. Note that any workflows running between deleting the old tag and pushing the new tag will fail.

‎action.yml‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
name: "Build and Deploy Documentation Site"
2+
description: "Convert Markdown documentation to a BCC documentation site"
3+
inputs:
4+
title:
5+
description: "Title of the generated website"
6+
required: true
7+
default: ${{ github.event.repository.name }}
8+
description:
9+
description: "Description of the generated website, used for the head meta tag"
10+
required: true
11+
default: ${{ github.event.repository.description }}
12+
docs-dir:
13+
description: "Directory where the docs are located"
14+
required: false
15+
default: "docs"
16+
branch:
17+
description: 'Which branch to use for "Edit this page on GitHub" links'
18+
required: false
19+
default: "main"
20+
base:
21+
description: "The base url for the website"
22+
required: false
23+
default: "/"
24+
collapse-sidebar:
25+
description: "Whether to collapse sidebar sections by default"
26+
required: false
27+
default: false
28+
auto-register-components:
29+
description: "Whether to automatically register Vue components"
30+
required: false
31+
default: false
32+
components-dir:
33+
description: "The directory from where Vue components should automatically be registered"
34+
required: false
35+
default: "src/components"
36+
debug-build:
37+
description: "Whether or not to enable debugging for the Vite build"
38+
required: false
39+
default: false
40+
public:
41+
description: "Whether or not to make the documentation publicly available (only works for private repositories)"
42+
required: false
43+
default: false
44+
authentication:
45+
description: "Which provider to use for the login flow when accessing the documentation"
46+
required: false
47+
default: "github"
48+
root:
49+
description: "Whether or not to deploy the site to the root of the custom container (true) or to a subfolder named after the repository (false)"
50+
required: false
51+
default: false
52+
runs:
53+
using: "composite"
54+
steps:
55+
- name: Generate GitHub App Token
56+
id: app-token
57+
uses: actions/create-github-app-token@v2
58+
with:
59+
app_id: ${{ secrets.APP_ID }}
60+
private_key: ${{ secrets.PRIVATE_KEY }}
61+
62+
- name: Check out base repository
63+
uses: actions/checkout@v5
64+
with:
65+
repository: bcc-code/developer.bcc.no
66+
ref: master
67+
token: ${{ steps.app-token.outputs.token }}
68+
69+
- name: Check out current repository
70+
uses: actions/checkout@v5
71+
with:
72+
path: source
73+
74+
- name: Zip Markdown files
75+
shell: bash
76+
run: |
77+
cd source/${{ inputs.docs-dir }}
78+
zip -r MarkdownDocs.zip .
79+
80+
- name: Zip Vue components (if they exist)
81+
shell: bash
82+
run: |
83+
if [ -d "source/${{ inputs.components-dir }}" ]; then
84+
cd source/${{ inputs.components-dir }}
85+
zip -r VueComponents.zip .
86+
fi
87+
88+
- uses: microsoft/variable-substitution@v1
89+
with:
90+
files: "vuepress/docs/.vuepress/data.json"
91+
env:
92+
title: ${{ inputs.title }}
93+
description: ${{ inputs.description }}
94+
base: ${{ inputs.base }}
95+
docsRepo: ${{ github.repository }}
96+
docsDir: ${{ inputs.docs-dir }}
97+
docsBranch: ${{ inputs.branch }}
98+
collapseSidebarSections: ${{ inputs.collapse-sidebar }}
99+
autoRegisterComponents: ${{ inputs.auto-register-components }}
100+
101+
- name: Get Token from GitHub
102+
id: token
103+
shell: bash
104+
run: |
105+
curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://github.com/bcc-code" | jq -r ".value" | echo -e "token=$(</dev/stdin)\n" >> $GITHUB_OUTPUT
106+
107+
- name: Upload Markdown files to azure storage
108+
shell: bash
109+
run: |
110+
curl --request POST \
111+
--header "Authorization: Bearer ${{steps.token.outputs.token}}" \
112+
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
113+
--form Docs=@source/${{ inputs.docs-dir }}/MarkdownDocs.zip \
114+
"https://developer.bcc.no/UploadMdContainer?aggregateContainer=mddocs&root=${{inputs.root}}"
115+
116+
- name: Upload Vue components to azure storage (if they exist)
117+
shell: bash
118+
run: |
119+
if [ -f "source/${{ inputs.components-dir }}/VueComponents.zip" ]; then
120+
curl --request POST \
121+
--header "Authorization: Bearer ${{steps.token.outputs.token}}" \
122+
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
123+
--form Docs=@source/${{ inputs.components-dir }}/VueComponents.zip \
124+
"https://developer.bcc.no/UploadDoc?isPublic=false&customContainerName=components"
125+
fi
126+
127+
- name: Download Markdown files from azure storage
128+
shell: bash
129+
run: |
130+
cd vuepress/docs/
131+
curl --request GET \
132+
--header "Authorization: Bearer ${{steps.token.outputs.token}}" \
133+
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
134+
"https://developer.bcc.no/GetDoc?container=mddocs" \
135+
--output MarkdownDocs.zip
136+
unzip -o MarkdownDocs.zip
137+
138+
- name: Download Vue components from azure storage
139+
shell: bash
140+
run: |
141+
mkdir -p vuepress/docs/.vuepress/auto-register-components
142+
cd vuepress/docs/.vuepress/auto-register-components
143+
curl --request GET \
144+
--header "Authorization: Bearer ${{steps.token.outputs.token}}" \
145+
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
146+
"https://developer.bcc.no/GetDoc?container=components" \
147+
--output VueComponents.zip
148+
if [ -f "VueComponents.zip" ]; then
149+
unzip -o VueComponents.zip
150+
rm VueComponents.zip
151+
fi
152+
153+
- name: Build VuePress site
154+
shell: bash
155+
run: |
156+
chmod -R u+rwX vuepress/docs || true
157+
cd vuepress
158+
npm ci && ${{ inputs.debug-build == true && 'DEBUG=*' || '' }} npm run build ${{ inputs.debug-build == true && '-- --debug' || '' }}
159+
160+
- name: Zips built site files
161+
shell: bash
162+
run: |
163+
cd vuepress/docs/.vuepress/dist
164+
zip -r Docs.zip .
165+
166+
- name: Upload VuePress site
167+
shell: bash
168+
run: |
169+
curl --request POST \
170+
--header "Authorization: Bearer ${{steps.token.outputs.token}}" \
171+
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
172+
--form Docs=@vuepress/docs/.vuepress/dist/Docs.zip \
173+
"https://developer.bcc.no/UploadDoc?isPublic=${{inputs.public}}&auth=${{inputs.authentication}}&customContainerName=docs"

‎workflows/release.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Publish Release
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
tags:
7+
- "v*"
8+
9+
env:
10+
CI: true
11+
12+
permissions:
13+
contents: read
14+
15+
jobs:
16+
build:
17+
permissions:
18+
contents: write # for softprops/action-gh-release to create GitHub release
19+
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- uses: actions/checkout@v3
24+
25+
- run: git fetch --tags -f
26+
27+
- name: Resolve version
28+
id: vars
29+
run: |
30+
echo "TAG_NAME=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV
31+
32+
- name: Release
33+
uses: softprops/action-gh-release@v1
34+
with:
35+
tag_name: ${{ env.TAG_NAME }}
36+
generate_release_notes: true

0 commit comments

Comments
 (0)