Private Modules and Packages

Configure tokens to access private Hugo modules and npm packages, both locally and as part of CI/CD.

  Warning

The information on this page is preliminary and subject to change. Please raise an issue  when the provided information is unclear or incorrect.

Local Development  

Use a combination of environment variables and credential management to safely configure your tokens. The authentication is slightly different for private Hugo modules and npm packages.

Hugo Modules  

Hinode provides several themes and modules as a private Hugo module. You will need a fine-grained personal access token with read access to the contents and metadata of those private Hugo modules. The following two sections explain two available options on how to configure access to private Hugo modules.

Using GitHub Credential Manager (Preferred)  

GitHub provides a CLI  to enable authentication to private and public repositories. When using the command gh auth, the CLI tool opens a new browser window, where you can authenticate yourself with GitHub. The login procedure supports both login/password and tokens. By default, this procedure supports one account per domain only. Run the following command to instruct git to use the full HTTP path of the repository instead.

git config --global credential.useHttpPath true

git config --global credential.useHttpPath true

From now on, git will trigger a authentication request when accessing a new repository. The GitHub CLI will store this information in the credential manager provided by your Operating System.

Using Git Configuration (Alternative)  

As an alternative, you can also use a git configuration that links a Personal Access Token to a specific domain using the insteadOf directive. For example, you can use the following command to configure a token to access the private module github.com/gethinode/mod-bookshop. Replace <PAT> with the actual token value. The value for <ACCOUNT> can be anything (but is mandatory). Git stores the token as plain text in ~/.gitconfig, which is less secure than the preferred approach.

git config --global \
url."https://<ACCOUNT>:<PAT>@github.com/gethinode/mod-bookshop".insteadOf \
"https://github.com/gethinode/mod-bookshop"

git config --global \
url."https://<ACCOUNT>:<PAT>@github.com/gethinode/mod-bookshop".insteadOf \
"https://github.com/gethinode/mod-bookshop"

To update an existing token, you need to manually remove the existing entry in ~/.gitconfig and rerun the git config command. Alternatively, you can update the existing token in the ~/.gitconfig file yourself.

Npm Packages  

Hinode publishes several utilities as npm packages on npm.pkg.github.com. The GitHub package registry requires authentication for both public and private packages. We will use a personal access token (classic) with read:packages privileges to access them. By using a credential manager and command substitution, we avoid storing the sensitive information in-memory or as plain text in a file.

Follow the instructions for your operating system below.

security add-generic-password -a "$USER" -s 'NPM_TOKEN' -w

export NPM_TOKEN=$(security find-generic-password -s 'NPM_TOKEN' -w)

sudo apt-get install libsecret-tools

secret-tool store --label="Hinode npm token" provider npm profile hinode key-pair secret

export NPM_TOKEN=$(secret-tool lookup provider npm profile hinode key-pair secret)

We will now use a npm configuration file to set up the authentication token. Create a new file .npmrc in the root folder of your local repository with the following content:

@gethinode:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

npm will expand the variable ${NPM_TOKEN}, which has been defined as environment variable using command substitution in the previous step.

CI/CD Workflows  

You can use repository secrets to safely store the tokens in a GitHub Action. By using variable substitution, you can inject the tokens into the configuration files for Hugo modules and npm packages.

Hugo Modules  

  Caution

Avoid using the .netrc file for local development, as this intervenes with your current git authentication. Use the method described in Local Development instead.

Generate a .netrc file for the current user of the GitHub runner to configure access to a private Hugo module. Configure HUGO_TOKEN as repository secret. Then use the following step prior to the Hugo build step to generate (or overwrite) the ~/.npmrc file. Go, the underlying module framework used by Hugo, will use this token for all private modules hosted on github.com.

# Generate a .netrc file with the substituted HUGO_TOKEN secret for the current user
- name: Use GitHub token
    run: echo "machine github.com login ci password ${{ secrets.HUGO_TOKEN }}" > ~/.netrc

- name: Build main site
    run: npm run build

Npm Packages  

You can use an .npmrc file with the authentication token to configure the access to a private npm package. Configure NPM_TOKEN as repository secret. Then use the following step prior to the npm installation step to generate (or overwrite) the .npmrc file. npm will use this token for all packages owned by the @gethinode organization, hosted on the GitHub package registry npm.pkg.github.com.

- name: Update .npmrc
    run: |
    echo "@gethinode:registry=https://npm.pkg.github.com/" > .npmrc
    echo "//npm.pkg.github.com/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc

- name: Perform clean install of npm
    run: npm i
    shell: bash

Example GitHub Action  

The following example action builds a Hinode website that uses both private npm packages and Hugo modules. Deploy this action to your .github folder as usual.

name: Build
on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: lts/*
        cache: 'npm'
        cache-dependency-path: '**/package-lock.json'

    # Generate a local .npmrc file with the substituted NPM_TOKEN secret
    - name: Update .npmrc
      run: |
        echo "@gethinode:registry=https://npm.pkg.github.com/" > .npmrc
        echo "//npm.pkg.github.com/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc

    - name: Perform clean install of npm
      run: npm i
      shell: bash

    # Generate a .netrc file with the substituted HUGO_TOKEN secret for the current user
    - name: Use GitHub token
      run: echo "machine github.com login ci password ${{ secrets.HUGO_TOKEN }}" > ~/.netrc

    - name: Build main site
      run: npm run build