Skip to content

FAQ

Jump to bottom
Kjetil Klepper edited this page Dec 5, 2025 · 15 revisions

Audience

This FAQ is intended as an internal resource for people working on the FEGA Norway source code in this mono repo.

Commits

  • How to name new branches
  • How to write commit messages

Pull Requests

  • How to name PRs: type: description
  • How to merge PRs: First “rebase” (if necessary) then use “merge commit”

Versioning and Tagging Rules

Components

We have these components:

  • lega-commander
  • e2eTests
  • clearinghouse
  • crypt4gh
  • tsd-file-api-client
  • cega-mock
  • localega-tsd-proxy
  • mq-interceptor
  • tsd-api-mock
  • FEGA-Norway(our main repository)

Triggering a New Tag

  • A new tag for a component is triggered when there are changes in that component’s path.

Default Behavior

  • By default, when a component changes, the patch part of its version is incremented.

Overriding the Default

  • To bump the major or minor part instead of patch, you must explicitly mark it in a commit message.

Supported Formats

#major_componentName  
#minor_componentName  
#patch_componentName

Example

implement getVisa() #minor_clearinghouse

This bumps the minor version of clearinghouse. Other changed components in the same branch will follow the default patch bump unless explicitly marked.

Commit Message Check

There is a workflow that validates commit messages for correct component names. If your commit message includes #major, #minor, or #patch, the workflow checks that the referenced component name matches an existing component. The workflow fails if there is a mismatch.

Multiple Components in One Branch

  • You can specify bumps for multiple components across different commit messages in the same branch.
  • Each mentioned component will bump according to the highest specified level (major > minor > patch).
  • This allows you to bump versions of different components even if the bump markers are spread across multiple commits.

Example:

update encryption #minor_crypt4gh
add new API endpoint #major_clearinghouse

This bumps the minor version of clearinghouse and the major version of crypt4gh.

Multiple Components in One Commit

  • You can mention multiple components in the same commit message.
  • Each mentioned component will bump according to the specified level.

Example:

upgrade to Java 25 #major_clearinghouse #major_crypt4gh

This bumps the major version of both clearinghouse and crypt4gh.

Conflicting Bumps

  • If multiple bump markers are specified for the same component in the same branch, the highest level takes effect.

Priority order:

  1. major
  2. minor
  3. patch

Example:

refactor X #minor_clearinghouse #major_clearinghouse
or
refactor X #minor_clearinghouse
upgrade X #major_clearinghouse

This results in a major bump for clearinghouse.

Important note

  • As it was said, a new tag for a component is triggered only when there are changes in that component’s path.
  • If a commit message includes a bump for a component that has no changes in that branch, no new tag will be created for it.

Example:

add new feature #minor_clearinghouse

If there are no changes under the /clearinghouse path, no new package will be released for clearinghouse.

Forgot to Add a Bump Marker?

If you forget to include a bump marker (e.g. #minor_clearinghouse) in your commit message, you have two options before merging:

1. Amend the Commit (recommended if it’s the most recent commit)

Suppose your last commit was:

git commit -m "implement getVisa()"

You realize you forgot the bump marker for clearinghouse. Amend the commit:

git commit --amend

Edit the commit message to:

implement getVisa() #minor_clearinghouse

Then push the updated commit (force-push if the branch was already pushed):

git push --force

Now, when the branch is merged:

  • Changes in /clearinghouse will trigger a minor version bump.
  • Other components follow default behavior unless explicitly marked.

2. Add a New Commit (alternative if you don’t want to rewrite history)

If you prefer not to amend, you can create a new commit just for the missing marker:

add missing marker #minor_clearinghouse

When the branch is merged:

  • The bump marker will still be recognized.
  • Other components follow their default behavior unless explicitly marked.

Various

  • How to increment the minor/major version number of an artifact (rather than the automatic patch-increment)
  • SpotlessCheck and spotlessApply

JAR signing keys

In order to publish to Maven Central, all artifacts must be signed with a GPG key. A new signing key can be created with the following command:

gpg --gen-key

If you get an error saying "gpg: agent_genkey failed: No pinentry", you can add the argument --pinentry-mode loopback.

Enter the following information in the interactive dialog. You must also choose a password to protect the private key (for instance with this generator)

Real name :  Federated EGA Norway
Email     :  fega-norway-support@elixir.no

You can list all the keys in your "keyring" with the command: gpg --list-keys. They will be shown like this:

pub   ed25519 2025-04-09 [SC] [expires: 2027-04-09]
      A9CD638727AE6815FB12EB8FF97FCD66B6BD0F8D
uid           [ultimate] FEGA Norway Team <fega-norway-support@elixir.no>
sub   cv25519 2025-04-09 [E] [expires: 2027-04-09]

The hex-string shown on the second line here is the fingerprint of the key, which serves as a unique identifier.

To export the private key in ASCII-format (rather than binary), you can use the "armor" option in combination with "export-secret-keys". This will give you a multi-line file with a header and footer (on the form -----BEGIN PGP PRIVATE KEY BLOCK-----). However, since Gradle is not able to import variables that includes newlines, we must convert the key file to base64 format without any newlines. This can be done with the following command:

gpg --armor --export-secret-keys <fingerprint> | base64 -w 0

The result will be a single line with about 1220 characters, looking something like this: LS0tLS1CRUdJTiBQ.....xPQ0stLS0tLQo=. Note that if you run the export command above multiple times, the resulting output will be different each time. This is because the private key is encrypted in the output file using your chosen password and a random salt, and the salt value is generated anew for each export, which means that the encryption will look different. But the decrypted key will still be the same in all cases.

To rotate the signing key in GitHub, go to the FEGA-Norway repository and click on "Settings". Then select "Actions" from the "Secrets and Variables" drop-down menu in the panel on the left. Click the pencil-icon on the SIGNING_KEY_BASE64 repository secret to edit it, and paste in the key on a single line. Update the SIGNING_PASSWORD secret to the corresponding password for the key.

The public part of the signing key can be used to verify signatures. This is not really used by us, but to allow other people the chance to verify the signatures of our Maven Central artifacts, we must upload the public key to a public key server. That can be done with this command:

gpg --keyserver <keyserver> --send-keys <fingerprint>

So far, we have made the public key available on two servers:

  • keyserver.ubuntu.com
  • keys.openpgp.org

The OpenPGP key server requires you to verify the key by clicking on a link in an email sent to fega-norway-support@elixir.no. It is possible to upload different versions of the "same key" (with same owner/email), and they will all be listed if you search with the email address.

Secrets

  • Where are the keys
  • how to rotate them
  • Where is the GPG signing key published (public servers)

GitHub workflows

This is a list of all GitHub workflows in this repository, along with a brief description and their respective triggers. For better understanding, you can also check the workflow YAML files in the .github/workflows directory.

Workflow Description Trigger
action-linter.yml Lints all YAML, JSON, and GitHub Action files in pull requests using a JSON/YAML validator and Actionlint. Pull requests modifying *.yaml, *.yml, or *.json files
build-and-test.yml Builds the project with Gradle and runs unit and end-to-end tests. On any push
check-commit-message.yml Checks PR commit messages for invalid version bumps and fails if typos are found. Pull requests targeting main branch
codeql.yml Performs CodeQL security analysis on Java and Go code. Pushes to main branch
detect-changed-components.yml Detects which components in the repo have changed and outputs a matrix for use in other workflows. Called via workflow_call (used by other workflows)
format-code.yml Checks and applies code formatting via Gradle Spotless and commits changes automatically if needed. Pushes or PRs affecting lib/**, services/**, or buildSrc/** on main
pre-release-check.yml Performs a dry-run build/publish for changed components (JARs, Docker images, Go binaries) and generates changelogs; ensures nothing will break in the release process. Pull requests targeting main branch
publish-and-release.yml Runs after a merged PR, publishes new versions of changed components (JARs, Docker images, Go binaries), creates GitHub Releases, tags releases, and generates changelogs. Closed and merged pull requests targeting main
remove-old-images.yml Scheduled workflow that removes old or untagged Docker images from the GitHub Container Registry. Scheduled (cron) Mondays at 02:10 UTC, or manually via workflow dispatch
scan-images.yml Runs Trivy vulnerability scans on updated Docker images for localega-tsd-proxy and mq-interceptor and uploads results to GitHub Security. Closed/merged PRs to main that modify services/localega-tsd-proxy/** or services/mq-interceptor/**

e2eTest

  • Missing parts of how to run e2etest (only available as comments in a merged PR#)
  • What to do when the e2etest is not working? (not relying on IDE/Intellij)

Web pages

  • How to maintain the FEGA Norway Web Pages

The FEGA Norway web pages are static web pages maintained in a separate repo (link).

A checked-out version of the web pages must be available in a folder that is mounted by the LocalEGA-TSD-Proxy service to serve this content. An update to the content on a web server can then simply be done by pulling updates from GitHub.

NB! Access to the .github folder inside this web-site folder needs to be blocked at nginx or similar level

NB2! Although static, the web-pages have a LS AAI login button integrated needing parameters including redirection to REST API endpoints in the LocalEGATSDProxy service upon completion.

Clone this wiki locally