Skip to content

Commit 4333d86

Browse files
tdgroottdgroot
authored
Merge pull request #115 from ByteInternet/add_github_gitlab_docs
2 parents 2cc96bf + f29b12a commit 4333d86

File tree

6 files changed

+359
-8
lines changed

6 files changed

+359
-8
lines changed

‎.github/workflows/deploy.yaml‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,9 @@ jobs:
4848
if: github.ref != 'refs/heads/master'
4949
container: quay.io/hypernode/deploy:3-php8.1-node18
5050
steps:
51-
- uses: actions/checkout@v2
51+
- uses: actions/checkout@v3
52+
with:
53+
fetch-depth: 0
5254
- name: download build artifact
5355
uses: actions/download-artifact@v3
5456
with:
@@ -65,11 +67,31 @@ jobs:
6567
- name: Get brancher hostname
6668
id: get_brancher_hostname
6769
run: echo "BRANCHER_URL=https://$(jq .hostnames[0] deployment-report.json -r)" >> $GITHUB_OUTPUT
70+
- name: Get changed pages
71+
id: changed_pages
72+
run: |
73+
git config --global --add safe.directory $(pwd)
74+
commits=${{ github.event.pull_request.commits }}
75+
if [[ -n "$commits" ]]; then
76+
# Prepare enough depth for diffs with target branch
77+
git fetch --depth="$(( commits + 1 ))"
78+
fi
79+
result="$(python3 ci/bin/get_changed_urls.py \
80+
${{ github.event.pull_request.base.sha }} \
81+
${{github.event.pull_request.head.sha}} \
82+
--base-url=${{ steps.get_brancher_hostname.outputs.BRANCHER_URL }}
83+
)"
84+
echo "$result"
85+
echo "CHANGED_PAGES<<EOF" >> $GITHUB_OUTPUT
86+
echo "$result" >> $GITHUB_OUTPUT
87+
echo "EOF" >> $GITHUB_OUTPUT
88+
shell: bash
6889
- name: Comment hostname on PR
6990
uses: thollander/actions-comment-pull-request@v1
7091
with:
7192
message: |
72-
Acceptance server is available at ${{ steps.get_brancher_hostname.outputs.BRANCHER_URL }}
93+
Acceptance server is available at ${{ steps.get_brancher_hostname.outputs.BRANCHER_URL }}.
94+
${{ steps.changed_pages.outputs.CHANGED_PAGES }}
7395
7496
deploy_production:
7597
needs: build
@@ -81,7 +103,7 @@ jobs:
81103
if: github.ref == 'refs/heads/master'
82104
container: quay.io/hypernode/deploy:3-php8.1-node18
83105
steps:
84-
- uses: actions/checkout@v2
106+
- uses: actions/checkout@v3
85107
- name: download build artifact
86108
uses: actions/download-artifact@v3
87109
with:

‎ci/bin/get_changed_urls.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import argparse
2+
import re
3+
import subprocess
4+
from typing import Tuple
5+
6+
CHANGED_PATTERN = re.compile(r"^[AM]")
7+
8+
9+
def parse_args() -> Tuple[str, str, str]:
10+
parser = argparse.ArgumentParser()
11+
parser.add_argument("start_commit")
12+
parser.add_argument("end_commit")
13+
parser.add_argument("--base-url", default="")
14+
15+
args = parser.parse_args()
16+
17+
return args.start_commit, args.end_commit, args.base_url.rstrip("/")
18+
19+
20+
def main():
21+
start_commit, end_commit, base_url = parse_args()
22+
diff_command = [
23+
"git",
24+
"diff",
25+
"--name-status",
26+
"-M",
27+
"--stat",
28+
start_commit,
29+
end_commit,
30+
]
31+
output = subprocess.check_output(diff_command, encoding="utf-8")
32+
changed_files = filter(CHANGED_PATTERN.match, output.splitlines())
33+
changed_files = map(lambda x: x.split("\t")[1], changed_files)
34+
changed_markdown_files = filter(lambda x: x.endswith(".md"), changed_files)
35+
changed_markdown_files = list(changed_markdown_files)
36+
37+
if changed_markdown_files:
38+
print("Changed pages:")
39+
for file in changed_markdown_files:
40+
file = re.sub("^docs/", "", file)
41+
file = re.sub(".md$", ".html", file)
42+
print("- " + base_url + "/" + file)
43+
44+
45+
if __name__ == "__main__":
46+
main()

‎docs/hypernode-deploy/pipelines/bitbucket-pipelines.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Bitbucket Pipelines
22

3-
TODO
3+
This article is currently work in progress!

‎docs/hypernode-deploy/pipelines/github-actions.md‎

Lines changed: 175 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,176 @@
1-
# Github Actions
1+
# GitHub Actions
22

3-
TODO
3+
## Configuring deployment environments
4+
5+
To start using GitHub Actions, we need to prepare the environments we want to deploy to.
6+
7+
For example, these environments can be:
8+
9+
- production
10+
- acceptance (or staging)
11+
- test
12+
13+
### Configuring the production environment
14+
15+
Hypernode Deploy will need a pair of SSH keys for authentication to the server.
16+
17+
First, we generate an SSH keypair on the production server, copy the public key to the `~/.ssh/authorized_keys` file
18+
and encode the private key with base64. We'll use this base64-encoded private key later on.
19+
20+
```console
21+
app@abc-example-magweb-cmbl:~$ ssh-keygen -t ed25519 -C gh-actions-deploy -f gh-actions-deploy -q -P ""
22+
app@abc-example-magweb-cmbl:~$ cat gh-actions-deploy.pub >> ~/.ssh/authorized_keys
23+
app@abc-example-magweb-cmbl:~$ cat gh-actions-deploy | base64 -w0 # encode the private key with base64
24+
LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
25+
```
26+
27+
Now go to your GitHub project and go to **Settings -> Environments**.
28+
29+
1. Create a new environment called `production`, if it doesn't exist yet.
30+
1. Click the `production` environment and click `Add secret`.
31+
1. Set the **Name** to `SSH_PRIVATE_KEY`.
32+
1. Set the **Value** to the base64-encoded private key we generated earlier.
33+
1. Click **Add secret**.
34+
35+
### Configuring the acceptance environment
36+
37+
If you have an acceptance (or staging) environment, repeat the same steps for the production environment, but now for
38+
your acceptance environment, with the GitHub environment name `acceptance`.
39+
40+
## Build
41+
42+
To get started, we need to make sure the `.github/workflows` directory structure exists.
43+
44+
```bash
45+
mkdir -p .github/workflows
46+
```
47+
48+
Then create the file `.github/workflows/build.yml` with the contents below.
49+
This workflow will be used in other workflows.
50+
51+
```yaml
52+
name: Build application
53+
54+
on:
55+
workflow_call:
56+
57+
jobs:
58+
build:
59+
runs-on: ubuntu-latest
60+
container: quay.io/hypernode/deploy:3-php8.1-node18
61+
steps:
62+
- uses: actions/checkout@v3
63+
- uses: actions/cache@v3
64+
with:
65+
path: /tmp/composer-cache
66+
key: ${{ runner.os }}-composer
67+
- uses: webfactory/ssh-agent@v0.7.0
68+
with:
69+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
70+
- run: hypernode-deploy build -vvv
71+
- name: archive production artifacts
72+
uses: actions/upload-artifact@v3
73+
with:
74+
name: deployment-build
75+
path: build/build.tgz
76+
retention-days: 7
77+
```
78+
79+
````{note}
80+
Don't forget to set the specifications of the image to what your project needs. The same goes for the deploy steps.
81+
For example, if your project needs PHP 7.4 and Node.js 16, set the image to:
82+
```yaml
83+
jobs:
84+
build:
85+
container: quay.io/hypernode/deploy:3-php7.4-node16
86+
...
87+
```
88+
````
89+
90+
## Deploy to production
91+
92+
Create a file called `.github/workflows/deploy_production.yml` with the following contents.
93+
94+
```yaml
95+
name: Deploy application to production
96+
97+
on:
98+
push:
99+
branches:
100+
- 'master' # production branch
101+
102+
jobs:
103+
build:
104+
uses: ./.github/workflows/build.yml
105+
106+
deploy:
107+
needs: build
108+
runs-on: ubuntu-latest
109+
# Concurrency takes any arbitrary value, but this prevents multiple deployments happening at the same time.
110+
# We set the concurrency to production for this deployment workflow.
111+
concurrency: production
112+
environment:
113+
name: production
114+
url: https://www.example.com
115+
container: quay.io/hypernode/deploy:3-php8.1-node18
116+
steps:
117+
- uses: actions/checkout@v3
118+
- name: download build artifact
119+
uses: actions/download-artifact@v3
120+
with:
121+
name: deployment-build
122+
path: build/
123+
- uses: actions/cache@v3
124+
with:
125+
path: /tmp/composer-cache
126+
key: ${{ runner.os }}-composer
127+
- uses: webfactory/ssh-agent@v0.7.0
128+
with:
129+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
130+
- run: mkdir -p $HOME/.ssh
131+
- run: hypernode-deploy deploy production -vvv # Deploy production stage defined in deploy.php
132+
```
133+
134+
## Deploy to acceptance
135+
136+
Create a file called `.github/workflows/deploy_acceptance.yml` with the following contents.
137+
138+
```yaml
139+
name: Deploy application to acceptance
140+
141+
on:
142+
push:
143+
branches:
144+
- 'acceptance' # acceptance/staging branch
145+
146+
jobs:
147+
build:
148+
uses: ./.github/workflows/build.yml
149+
150+
deploy:
151+
needs: build
152+
runs-on: ubuntu-latest
153+
# Concurrency takes any arbitrary value, but this prevents multiple deployments happening at the same time.
154+
# We set the concurrency to acceptance for this deployment workflow.
155+
concurrency: acceptance
156+
environment:
157+
name: acceptance
158+
url: https://acceptance.example.com
159+
container: quay.io/hypernode/deploy:3-php8.1-node18
160+
steps:
161+
- uses: actions/checkout@v3
162+
- name: download build artifact
163+
uses: actions/download-artifact@v3
164+
with:
165+
name: deployment-build
166+
path: build/
167+
- uses: actions/cache@v3
168+
with:
169+
path: /tmp/composer-cache
170+
key: ${{ runner.os }}-composer
171+
- uses: webfactory/ssh-agent@v0.7.0
172+
with:
173+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
174+
- run: mkdir -p $HOME/.ssh
175+
- run: hypernode-deploy deploy acceptance -vvv # Deploy acceptance/staging stage defined in deploy.php
176+
```

‎docs/hypernode-deploy/pipelines/gitlab-ci.md‎

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,111 @@
11
# Gitlab CI
22

3-
TODO
3+
## Configuring deployment environments
4+
5+
To start using Gitlab CI, we need to prepare the environments we want to deploy to.
6+
7+
For example, these environments can be:
8+
9+
- production
10+
- acceptance (or staging)
11+
- test
12+
13+
### Configuring the production environment
14+
15+
Hypernode Deploy will need a pair of SSH keys for authentication to the server.
16+
17+
First, we generate an SSH keypair on the production server, copy the public key to the `~/.ssh/authorized_keys` file
18+
and encode the private key with base64. We'll use this base64-encoded private key later on.
19+
20+
```console
21+
app@abc-example-magweb-cmbl:~$ ssh-keygen -t ed25519 -C gitlab-ci-deploy -f gitlab-ci-deploy -q -P ""
22+
app@abc-example-magweb-cmbl:~$ cat gitlab-ci-deploy.pub >> ~/.ssh/authorized_keys
23+
app@abc-example-magweb-cmbl:~$ cat gitlab-ci-deploy | base64 -w0 # encode the private key with base64
24+
LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
25+
```
26+
27+
Now go to your Gitlab project and go to **Deployments -> Environments**.
28+
29+
1. Create a new environment called `production`, if it doesn't exist yet.
30+
1. Go to **Settings -> CI/CD -> Variables**.
31+
1. Click `Add variables`.
32+
1. Set **Key** to `SSH_PRIVATE_KEY`.
33+
1. Set **Value** to the base64-encoded private key we generated earlier.
34+
1. Set **Environment scope** to `production`.
35+
1. If you don't have protected branches configured, uncheck the setting **Protect variable**.
36+
1. Check the setting **Mask variable**.
37+
1. Click **Add variable**.
38+
39+
### Configuring the acceptance environment
40+
41+
If you have an acceptance (or staging) environment, repeat the same steps for the production environment, but now for
42+
your acceptance environment, with the Gitlab environment name `acceptance`.
43+
44+
## Build
45+
46+
Create a file called `.gitlab-ci.yml` with the contents below.
47+
48+
This sets the container image, defines the CI/CD stages and defines the build step (part of the build stage).
49+
50+
```yaml
51+
# See https://quay.io/repository/hypernode/deploy?tab=tags for all possible tags.
52+
image: quay.io/hypernode/deploy:3-php8.1-node18
53+
54+
stages:
55+
- build
56+
- deploy
57+
58+
build:
59+
stage: build
60+
only:
61+
- merge_requests
62+
- acceptance
63+
- master
64+
script:
65+
- hypernode-deploy build -vvv
66+
artifacts:
67+
paths:
68+
- build/**
69+
```
70+
71+
````{note}
72+
Don't forget to set the specifications of the image to what your project needs.
73+
For example, if your project needs PHP 7.4 and Node.js 16, set the image to:
74+
```yaml
75+
image: quay.io/hypernode/deploy:3-php7.4-node16
76+
```
77+
````
78+
79+
## Deploy to production
80+
81+
Add the following to the `.gitlab-ci.yml` file.
82+
83+
```yaml
84+
# Deploy to production
85+
deploy_production:
86+
stage: deploy
87+
only:
88+
- master # production branch
89+
script:
90+
- hypernode-deploy deploy production
91+
environment:
92+
name: production
93+
url: https://www.example.com
94+
```
95+
96+
## Deploy to acceptance
97+
98+
If you have an acceptance (or staging) stage in your deployment flow, here's an example on how to deploy that.
99+
100+
```yaml
101+
# Deploy to acceptance
102+
deploy_acceptance:
103+
stage: deploy
104+
only:
105+
- acceptance # acceptance/staging branch
106+
script:
107+
- hypernode-deploy deploy acceptance
108+
environment:
109+
name: acceptance
110+
url: https://acceptance.example.com
111+
```

0 commit comments

Comments
 (0)