The source code for the zuehlke.github.io page.
The default branch is development
. All changes should be made via pull requests into that branch. The gh-pages
branch contains only the build, which is served on zuehlke.github.io. A build and
re-deployment is automatically triggered on every push to the develop
branch (see "Deployment and Automation" below).
The master
branch contains the last build of the old application, which is no longer being served.
In summary:
development
: default branch, pushes to this branch trigger a build and re-deploymentgh-pages
: deployed branch containing the static web pagemaster
: no longer in use, contains the latest build of the old websiteWeb application
npm install
to install all dependenciesnpm start
to open the app in a local development server (http://localhost:3000/)npm run build
to create a production build in the build
directorynpm run test
to run all tests (no tests defined at the moment)Automation
.github/actions/data-update
, run pip install -r requiremets.txt
, preferably in a virtualenv
environmentGITHUB_PAT=<PAT_PUBLIC> OUTPUT_DATA_DIR=<some_dir> EXTERNAL_CONTRIBUTIONS_FILE=<path_to_external_contributions.csv> python src/main.py
where
PAT_PUBLIC
is a public-access-only GitHub PAT (see Resources)some_dir
is the absolute path to the desired data output directory (usually, the src/data
subdirectory of a clone
of this repository)To avoid unnecessary GitHub Actions workflow runs, it is recommended to not commit directly to the develop
branch,
but rather work with pull requests instead. Alternatively, disable the [push] Build and Deploy
workflow in the
Actions tab during development. Keep in mind though that this will also stop data updates (contributions, people) from
being automatically merged into the production branch. Both workflows can also be manually triggered in the Actions
tab (preferably on the develop
branch).
The frontend is written in React + TypeScript and is managed through create-react-app. It has the following pages:
Contributions
: All public repositories owned by the Zühlke organization. People
: All non-concealed members of the Zuehlke organization. This may include Zühlke alumni who are still actively
contributing to Zuehlke repositories. Organization membership is managed by Ben Millo.The data for these two pages are loaded client-side from src/data/contributions.json
and src/data/people.json
respectively. These files are automatically generated by the data-update
GitHub action (see Data Update Automation)
and contain publicly available data fetched from the GitHub API, such as a repository's name, description and stargazer
count, and a person's GitHub name, full name, bio and avatar.
The website is mobile-responsive and its design approximates that of the Zühlke corporate page.
Hero image source: GettyImages stock photo from Zuehlke Templafy.
GitHub Pages is a feature offered by GitHub which allows every user or organization to
serve the contents of one repository as a static website. The name of that repository has to be
<user_or_org>.github.io
, which will also be the default URL for the resulting web page. In our case, this is
zuehlke.github.io
, and http://zuehlke.github.io respectively.
In the settings for a GitHub Pages repository, we can specify the branch which should be served as the website. In our
case, the branch to be served is set to gh-pages
. It therefore needs to contain the built, static website content,
rather than any source code. A GitHub Actions workflow is set up to automatically build the application on every push
to the develop
branch and commit the results to the gh-pages
branch (see CI/CD).
On every push to the develop
branch, the [push] Build and Deploy
GitHub Actions workflow is triggered, which is
defined in .github/workflows/build-and-deploy.yml. This workflow checks out
the develop
branch, builds the application using npm run build
and commits the contents of the build
directory
to the gh-pages
branch.
The secrets.GITHUB_TOKEN
value used in the build_and_deploy
job's final step is a special environment variable
automatically provided to every GitHub Actions workflow. This token grants the workflow full permissions on the
repository it is running for.
This workflow can also be manually triggered in the repository's Actions tab. Make sure to select the branch with the
most up-to-date workflow description (i.e. build-and-deploy.yml
file) (usually the default branch, develop
).
[schedule] Update from API
workflow, defined by
.github/workflows/update-from-api.yml (file contains additional
documentation).update-from-api.yml
file.src/consts.py
. The following parameters are available:
ENV_GITHUB_PAT
: Name of the environment variable which provides the GitHub PATENV_OUTPUT_DATA_DIR
: Name of the environment variable which provides the full path to the data output directoryENV_EXTERNAL_CONTRIBUTIONS_FILE
: Name of the environment variable which provides the full path to the csv file with external
contributions (name and repo)API_REQUEST_DELAY_SEC
: Number of seconds to wait before every API request, to avoid flooding the APIRATE_LIMIT_BUFFER_SEC
: Number of seconds to wait after a rate limit is supposed to be lifted, to avoid overlapRATE_LIMIT_MAX_AGE_SEC
: Maximum number of seconds since the rate limit update before the current rate limit status information is
considered stale and has to be updated.MAX_RETRIES
: The maximum number of retries when a request fails (also applies for failed requests due to rate limitation). After
that, the execution fails. 0
when deploying to platforms with usage-based pricing (e.g. GitHub Actions), since
waiting for a rate limit to be lifted will result in additional compute time, which can be expensive.CONTRIBUTIONS_FILENAME
: Name of the contributions output file in the data output directory (file will be created or overwritten).EXTERNAL_CONTRIBUTIONS_FILENAME
: Name of the external contributions output file in the data output directory (file will be
created or overwritten).PEOPLE_FILENAME
: Name of the people output file in the data output directory (file will be created or overwritten). update-from-api.yml
file) (usually the default branch, develop
).develop
).with.ref
field for the workflow's Checkout
step.develop
. Hence, the automated push will also trigger a re-build of the application into the
gh-pages
branch.GITHUB_PAT
and OUTPUT_DATA_DIR
.
OUTPUT_DATA_DIR
input is set to ./src/data. This is the folder where the workflow writes the updated data to. It is also the location where the frontend reads the displayed data from.PAT_PUBLIC
: Has public-only access. Using this PAT for the custom action ensures that API calls won't return
private repositories or concealed organization members.PAT_PRIVATE
: Used for checking out the current repository. This token needs full access to private Org repos to
be able to clone the repository and push to it. Note that this PAT is specifically used in the Checkout step, in
lieu of the secrets.GITHUB_TOKEN
provided to every workflow and used by this action by default. This is due to the
fact that a push executed with secrets.GITHUB_TOKEN
does not trigger any subsequent actions (e.g. building the)
web application, nor does it count as "repository activity", which is required to avoid scheduled workflows getting
automatically deactivated.repo
scope.
Settings -> Developer settings -> Personal access tokens
.PAT_REPO
to this repository's Secrets.Settings -> Developer settings -> Personal access tokens
.PAT_PUBLIC
to this repository's Secrets.The initial plan was to deploy the automation script on Azure, most likely as a Docker container with a cron job which automatically executes the script once per day. However, this approach was discarded due to the following reasons:
update-from-api.yml
action's trigger to workflow_dispatch
. The workflow
via a POST
request to
https://api.github.com/repos/Zuehlke/zuehlke.github.io/actions/workflows/update-from-api.yml/dispatches
, using the
PAT_REPO
token, or a different PAT with the same permission level (full private repo access).This section is only relevant for integrating the current forked branch into the mainline repository and can be removed afterwards. To integrate the revitalization, the following steps are required:
Zuehlke/zuehlke.github.io
to the Bot GitHub User.PAT_PUBLIC
and PAT_REPO
(see Resources) in the Bot GitHub User's account and add them to the
Zuehlke/zuehlke.github.io
repository's Secrets, using these exact names.SilasBerger/zuehlke.github.io@revitalize
into Zuehlke/zuehlke.github.io@develop
.[push] Build and Deploy
and [schedule] Update from API
.
.yml
file (e.g. change the workflow's
name, add a comment). This generally gets GitHub Actions to detect the added workflow.[push] Build and Deploy
workflow on the develop
branch, to build the application and
deploy to the gh-pages
branch.Zuehlke/zuehlke.github.io
repository settings, set the gh-pages
branch as the "deployed branch" in the
GitHub Pages section.[schedule] Update from API
workflow, check the repository's Actions
tab to verify that the job ran successfully. Keep in mind that a delay between the scheduled and the actual execution
time of up to 30 minutes is not unusual.