NHSE GitHub

Version Control & Project Management

• Official NHS England GitHub Organisation: github.com/nhsengland
• To request membership email: github@england.nhs.uk & jonathanpearson@nhs.net
• You can also request to join a team or set one up for your department, with the option to create a child team within it. When requesting the setup of a new team and/or its child team(s), please specify to administrators which handles should be designated as maintainers.
• You can use your personal GitHub account if you also do open-source work or setup a organisational one (put “nhs” in your username).

Note

Two Factor Authorisation must be switched on for all members.

Warning

Private repos are not visable for all members. To allow others to see private repos you need to add the everyone team with read permissions on the specific repo.

Moving GitHub Repositories to NHSE Organisation

1. Ensure you’re a member of the NHSE GitHub Organisation. If not, follow the instructions provided above to request access.
2. Navigate to the settings of your repository and find the “Transfer” option in the Danger Zone.
3. Select “NHS England” as the destination for your repository transfer.
4. Notify the organisation administrators about your transfer. Provide the following details:
   • Name of the repository
   • Repository visibility status (private/public)
   • The team(s) to assign repository and their respective permission levels: Read, Triage, Write, Maintain, Admin
   • Indicate whether any handles need extra permissions for the transferred repository; otherwise, all team members have equal access levels
   • Any external collaborators’ handles, if needed.
5. Ensure that the collaborators of the repository are notified to continue their contribution in the transferred repository.

GitHub Desktop

Note that the GitHub desktop app is available on Modern Desktop (see Company Portal > Apps) and can be installed on UDAL VMs. The tool greatly improves the Git experience and makes managing multiple software projects much easier.

GitHub Desktop screenshot

Resources

• GitHub Features (GitHub)
• Intro to Git (NHS Digital RAP)
• Ways of Working (NHS England - Draft)
• Version Control (GOV.Data Sci)
• Publishing Code (NHS Digital RAP)
• Social Coding (NHS Digital RAP)

GitHub Pages

Publish a Quarto website project to your GitHub pages using GitHub actions.

Add the GitHub Actions workflow to your project

Copy quarto-publish.yml to the folder .github/workflows/quarto-publish-example.yaml.

on:
  push:
    branches: main
  pull_request:
    branches: main

name: Render and Publish

# you need these permissions to publish to GitHub pages
permissions: 
    contents: write
    pages: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest    
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        
      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Publish to Github Pages (and render)
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
          path: docs/_site
          tinytex: true 
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note

If your Quarto project is not in the top level folder of your repository (in this case in /docs), then add the following path to the ‘Publish to GitHub Pages (and render)’ action:

- name: Publish to GitHub Pages (and render)
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
    path: docs
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Warning

Do not edit the GITHUB_TOKEN to add a personal secret to this file. This file has the same permissions as your repository, and might be publicly readable.

Configure the repository before publishing

Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run quarto publish gh-pages locally once. Make sure you’re running the command from within the working directory of your Quarto project in RStudio. You can verify the working directory by checking the top left corner of the R console window. If necessary, use the setwd() function in R or find the menu Session > Set Working Directory > Choose Directory to change the working directory to your project location.

You can also use the Render button, or check the Render on Save option on the editor toolbar:

RStudio editor toolbar

Commit and push the workflow

Now, add and commit the workflow file you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through GitHub pages.

Note

Note that GitHub Pages uses a gh-pages branch in your repository, which will be automatically created if one doesn’t exist. Read more: Publishing - GitHub Pages