Publishing LRGO documentation with GitHub and Cloudflare

High level description

Documentation pages are managed in a GitHbub repository and published as a website hosted on CloudFlare Pages.

When a user pushes a change to a published branch of the repository (e.g., main), an GitHub Action is triggered to build the documentation site using Quarto. The built site is then deployed to CloudFlare Pages, making the updated documentation available online.

Access to the documentation site is managed through CloudFlare’s access control features, which restrict access to specific users or groups. The access rule setting is configured to allow only members of the Laboratory-of-Gene-Regulation-Oxford GitHub organisation to view the documentation.

When a user tries to access the documentation site, CloudFlare initiates an authentication process using GitHub OAuth. The user is redirected to GitHub to log in and authorize access. Once authenticated, CloudFlare verifies the user’s membership in the specified GitHub organisation. If the user is a member, they are granted access.

Managing user access - adding/removing users

Someone who wants to access the documentation site must have a GitHub account.

An administrator of the Laboratory-of-Gene-Regulation-Oxford GitHub organisation on GitHub will invite the user to join the organisation using their GitHub username. Once the user accepts the invitation and becomes a member of the organisation, they will be able to access the documentation site.

To remove a user’s access, the administrator can remove the user from the organisation on GitHub. Once the user is no longer a member of the organisation, they will be denied any further access to the documentation site.

Technical details

This section provides more details on the setup for technical administrators. This configuration should only need to be modified for a change in access rules or choice of branch to publish.

GitHub Actions Workflow

The GitHub Actions workflow is defined in the .github/workflows/deploy.yml file in the github repository of the documentation git repository. Any changes here must be made in the branch being published (i.e. don’t change this in main if you want to publish from branch review)

The key values to set are:

on: 
    push: 
        branches: 
            - main   # Branch to publish from 
    
jobs:
    build-and-deploy:
        - name: Deploy to Cloudflare Pages 
        with:
            apiToken: ${{secrets.CLOUDFLARE_API_TOKEN }} # Secret 
            accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} # Secret 
            projectName: lgro-doc # Cloudflare Pages project name
            

Anyone with edit access to the repository is able alter this config file. The settings need to be consistent with Cloudflare set up, so be careful.

Cloudfare Pages Configuration

You will need admin access to the Cloudflare account where the Pages project is hosted. From this account you can obtain the accountId, and set up the API token with appropriate permissions.

The CloudFlare pages project name for the primary documentation branch is lgro-doc.

This will publish to https://lgro-doc.pages.dev

Cloudflare Access Configuration

In the Cloudflare dashboard, navigate to the “Zero Trust” section.

In the “Policies” tab, you manage the access rules. The policy “Allow LGRO GiHub” members” is the rule which grants access to members of the Laboratory-of-Gene-Regulation-Oxford. To change this policy, best option is to create a new policy and swap the pages project to use the new one (see below).

Alternatives to this policy are possible, for example to create a group in the GitHub organisation for documentation-readers and control which GitHub organisation members are in this group. This might be needed to restrict the number of active users of the CloudFlare pages site (there is a limit of 50) before costs are incurred.

Someone who has been granted read access to the documentation site becomes a CloudFlare user and will count against the user limit. It may be necessary to purge this list of users from time to time to remove people who are not likely to use the site.

In the “Access Control” tab select “Applications” and then select the application as the pages project name (lgro-doc) and edit to assign the approrpiate access policy.

Security testing

To confirm the access controls are working, the following test has bqeen performed:

Scenario: Deny access to non-members of the Laboratory-of-Gene-Regulation-Oxford GitHub organisation

Given a GitHub user who is not a member of the Laboratory-of-Gene-Regulation-Oxford

And the user is on a Private browsing/incognito window

When the user attempts to access the documentation site

Then the user is redirected to GitHub to log in

And after logging in a page from lgrotest.cloudflaareaccess.com is displayed with the message “That account does not have access”

And if the user enters email for login code email, then no email invitation is received.

Scenario: Grant access to new member of the Laboratory-of-Gene-Regulation-Oxford GitHub organisation

Given a GitHub user who has just accepted a new membership to the Laboratory-of-Gene-Regulation-Oxford

And the user is on a Private browsing/incognito window

When the user attempts to access the documentation site

Then the user is redirected to GitHub to log in

And after logging in, the index page of the documentation site is displayed

Scenario: Revoke access to member of the Laboratory-of-Gene-Regulation-Oxford GitHub organisation

Given a GitHub user who has been removed from membership of the Laboratory-of-Gene-Regulation-Oxford

And the user is on a Private browsing/incognito window

When the user attempts to access the documentation site

Then the user is redirected to GitHub to log in

And after logging in a page from lgrotest.cloudflaareaccess.com is displayed with the message “That account does not have access”