Academisation Nuget Packages

This repository is a mono-repo and contains a number of different Nuget packages used by the academisation process - A2B, Prepare Transfers and Prepare Conversions.

Each package folder contains it's own solution file and each package has it's own github workflows. See the readme files within each folder for details on the individual packages.

For additional information about working with GitHub Packages and Nuget see the official documentation

For further information on generating a GitHub PAT Token and authenticating with the GitHub Nuget Registry see https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry

If you are a windows user and are regularly prompted for GitHub credentials some of the suggestions in this article may help.

---

Using The Nuget Packages From Your Development Machine

The Nuget packages provided by this repository are served under the DfE-Digital organisation. The be able to use these Nuget Packages (and others) you must configure your development machine to have a new NuGet Package Source. To do this, you must first create a PAT token that has at least read access for packages.

NEVER commit your PAT token to GitHub or any other VCS !

Next add a package source to your NuGet configuration using the CLI. Use the following command, replacing [USERNAME] with your GitHub username, and [PAT-TOKEN] with the PAT token you just generated.

dotnet nuget add source --username "[USERNAME]" --password "[PAT-TOKEN]" --store-password-in-clear-text --name DfE "https://nuget.pkg.github.com/DFE-Digital/index.json"

Alternatively you may add a package source directly in Visual Studio.Once you have generated a PAT token you can add a new NuGet Package Source to visual studio. You may be prompted to sign in, if you are then enter your GitHub username and instead of the password enter the PAT token you generated.

---

Referencing the Nuget Registry From a GitHub Action That Directly Builds DotNet Projects

This applies when building dotnet solutions that reference the nuget registry directly within a GitHub action. If you are using a GitHub action to trigger a build that is within a DockerFile, see here

You can use the Nuget Registry from a GitHub action pipeline without need for a PAT token. GitHub creates a special token for use during the lifetime of the GitHub action. For your apps to be able to restore from the DfE nuget repository, add the followint two lines to your yml file before restoring packages

- name: Add nuget package source
  run: dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.pkg.github.com/DFE-Digital/index.json"

Referencing the Nuget Registry From a GitHub Action That Builds DotNet Projects Using A DockerFile

If you are using a DockerFile to build your dotnet projects, and triggering this from a GitHub action the steps involved in configuring the required Nuget source are different.

First you must update the GitHub action so that the GitHub_Token which is automatically generated by GitHub is available to the DockerFile build process.

In your DockerFile update the build step so that it includes a secrets section, or add to the existing one if you already have some.

The line you need to add is secrets: github_token=${{ secrets.GITHUB_TOKEN }}

Note that the name of the value (to the left of the '=' is important and must match what you use in the DockerFile).

Below is an example build step with the secrets line added in

      - name: Build and push docker image
        uses: docker/build-push-action@v3
        with:
          context: .
          file: Dockerfile
          build-args: COMMIT_SHA=${{ needs.set-env.outputs.checked-out-sha }}
          secrets: github_token=${{ secrets.GITHUB_TOKEN }}
          tags: |
            ${{ secrets.AZURE_ACR_URL }}/${{ env.DOCKER_IMAGE }}:${{ needs.set-env.outputs.branch }}
            ${{ secrets.AZURE_ACR_URL }}/${{ env.DOCKER_IMAGE }}:${{ needs.set-env.outputs.release }}
            ${{ secrets.AZURE_ACR_URL }}/${{ env.DOCKER_IMAGE }}:sha-${{ needs.set-env.outputs.checked-out-sha }}
            ${{ secrets.AZURE_ACR_URL }}/${{ env.DOCKER_IMAGE }}:latest
          push: true

Next you need to use the secret within your DockerFile build actions. In Docker the secrets need to be mounted, and are only available in the layer they are used.

This means that you mount the secret by passing an extra argument to the RUN command: RUN --mount=type=secret,id=github_token followed by the rest of your instructions. Note the id of the secret being mounted must match the name of the value set by the secrets: in the GitHub action yaml file.

Below is an example of mounting the secret (which has been given the id of github_token) and then using it by writing it out into the command that is being exectued by calling cat.

RUN --mount=type=secret,id=github_token dotnet nuget add source --username USERNAME --password $(cat /run/secrets/github_token) --store-password-in-clear-text --name github "https://nuget.pkg.github.com/DFE-Digital/index.json"

Below is a complete example of building a solution that depends on the Nuget Registry.

WORKDIR /build/Dfe.PrepareConversions
RUN --mount=type=secret,id=github_token dotnet nuget add source --username USERNAME --password $(cat /run/secrets/github_token) --store-password-in-clear-text --name github "https://nuget.pkg.github.com/DFE-Digital/index.json"
RUN dotnet restore Dfe.PrepareConversions.sln
RUN dotnet build -c Release Dfe.PrepareConversions.sln --no-restore
RUN dotnet publish Dfe.PrepareConversions -c Release -o /app --no-restore

Remember, the --mount=type=secret,... needs to be included for every instruction that requires the secret .

For more information on using GitHub tokens with Docker secrets, see https://docs.docker.com/build/ci/github-actions/secrets/

Locally Building Your DockerFile

When building images that use DockerFiles that require secrets, you can pass secret values by using the --secret CLI arguemnt. For more information, see this article https://render.com/docs/docker-secrets

---

Authoring new Nuget Packages

• Create a sub-folder for your package and make sure that this folder contains all of the files your package needs (except for GitHub workflows files), and that you don't rely on any files outside of this folder to build the package.

• Create your Nuget package in this folder

  • Nuget packages are created from dotnet Class Libraries.

  • If you are using other C# projects for reference, make sure that you do not copy any Package Identifiers. These must be unique for each package.

  • Nuget packages have their own versioning rules, make sure you understand them. See this article for info.

  • In the properties for your class library set the following

    • Generate NuGet package on build - suggested value: ticked

    • Package ID - suggested value: $(AssemblyName)

    • Title - set this to a user friendly title, it will be shown on by tools such as NuGet Package Manager

    • Package Version - A version number in the format of Major.Minor.Patch with an optional release suffix. this article for info

    • Authors - suggested value: DFE-Digital

    • Project Url - This should be the path to the sub folder of your nuget package, within this repository. Suggested value: https://github.com/DFE-Digital/academisation-nuget-packages/tree/main/[Your Sub-Folder]

    • ReadME - This should be a path to a ReadMe file explaining the purpose of your Package and how to use it. It is not the path to this file. Provide a ReadMe file in the sub-folder for your package. Suggested value: ..\README.md

    • Repository Url - This is the URL to the GitHub repository hosting the package source. The URL should be to the root of this repository. Suggested value: https://github.com/DFE-Digital/academisation-nuget-packages

    • Repository Type - The type of repository. By default it will be Git but it's recommended that you explicitly declare this. Suggested Value: git

    • Tag - a semi-colon delimited list of tags to associate with your NuGet package. In addition to your own, it's recommended that you use the following dfe;academisation

• Create a new workflow file in the .github/workflows folder to build your nuget package and push it to GitHub. This workflow will be specifically for your packagage so name it appropriately, something like [Your Package Name]-build-and-push-package.yml.

  An example workflow file has been provided to make it easier for you to integrate with GitHub actions. The example workflow will build your nuget packages in release mode and apply the package version from the C# project belonging to the package. You must make sure you maintain the version number of the package for everything to work correctly.

• Use the example-package-and-publish-workflow.yml file as a template to create yourself new work flow that will package your project into Nuget package format and then publish it to the Nuget registry. Make sure that you replace all of the placeholders with information unique to your Nuget package. The placeholder values are within square parenthesis ([]) for example `[NameOfYourPackage]

• Use the example-CI-workflow.yml file as a template to create yourself a worklfow that will trigger building and running unit tests for your Nuget package. Make sure that you replace all of the placeholders with information unique to your Nuget package. The placeholder values are within square parenthesis ([]) for example `[NameOfYourPackage]