HavNett troubleshooting#

Where to start if something goes wrong in the havnett.org publishing workflow#

Look through the pipeline described here, starting with Havnett source and moving downstream.

  • Do the repo contents look as expected?

  • Are you able to sphinx compile the contents of Havnett source on your local computer?

    • Execute the command make clean html from the root directory of Havnett source

      • Make sure Sphinx with Sphinx extensions are installed on your system.

      • Working html content should end up in build/html/{index.html, etc}

  • Have the automatic jobs executed sucessfully?

    • Go to Build -> Jobs in the left menu in gitlab.

    • You should see a list of jobs; sucessful ones should say “Passed”, failed ones say “Failed”

    • For failed jobs, click on the job ID to see the job output and diagnose what went wrong.

    • Check the jobs in both Havnett source and Havnett deploy

  • Are the git access tokens (allowing access to one repo from another) valid?

    • Had to set an expiration date within a year for these - have to generate new tokens annually and enter them in the upstream repository.

    • See Expired Gitlab credentials below for how to renew Gitlab.com token credentials.

  • Are the subscriptions to Cloudflare and Octauthent up-to-date?

Passwords and credentials#

NPI Ocean credentials (gitlab.com, Cloudflare, Octauthent, gmail.com) can be found in the (NPI-internal) havnett_source repository (under misc/).

Expired Gitlab credentials#

In order to be allowed to push from gitlab.npolar.no : havnett_source to gitlab.com : havnett_deploy, a security token is used in the pipeline. This token is generated at gitlab.com : havnett_deploy.

The token does not last indefinitely, but expires every year. Using an expired token will result in a failed pipeline job deploy_to_gitlab_com. The error message will look something like this:

remote: HTTP Basic: Access denied. If a password was provided for Git authentication, the password was incorrect or you're required to use a token instead of a password. If a token was provided, it was either incorrect, expired, or improperly scoped. See https://gitlab.com/help/topics/git/troubleshooting_git.md#error-on-git-fetch-http-basic-access-denied
fatal: Authentication failed for 'https://gitlab.com/NPIOcean/havnett_deploy.git/'
Cleaning up project directory and file based variables 00:01
ERROR: Job failed: exit code 128

The solution here is to replace the access token with a new one:

Step 1: Create a new Deploy Token#

  1. Log in as the NPIOcean user on gitlab.com.

  2. Go to https://gitlab.com/-/user_settings/personal_access_tokens.

  3. Click Add new token.

  4. Fill in the fields:

    • Token name: e.g., havnett-access-internal-gitlab-to-gitlab_com (doesn’t matter)

    • Expiry date: Set to the maximum (one year from today)

    • Scopes: Check write_repository (required for pushing)

  5. Click Create Token.

  6. Copy the token value immediately (you won’t see it again).

Step 2: Update the CI/CD variable in the source repository#

  1. Navigate to your source repository (https://gitlab.npolar.no/npiocean/docs/havnett_source).

  2. Go to Settings → CI/CD → Variables → Add Variable.

  3. Under CI/CD Variables, find the CI_DEPLOY_TOKEN key and click Edit (pencil symbol) under Actions:

  4. Replace the token in Value field with the one from Step 1. (Long string, should start with “glpat-“)

  5. Click Save changes

Step 3: Verify the GitLab CI script#

Try rerunning the failed pipeline at gitlab.npolar.no/npiocean/docs/havnett_source/-/pipelines.

Confirm that the job completed. You should see a new, successful commit at https://gitlab.com/NPIOcean/havnett_deploy.