Skip to main content

Publishing a Release

This guide covers how to publish an official biannual UN/LOCODE release. The process uses a release-first approach — the Secretariat creates the release with all accompanying documentation in a single step, and the automated pipeline handles the rest.

Prerequisites​

Before creating a release, ensure that:

  • All locode changes for the release period have been merged to the main branch
  • The Secretariat Notes document (.doc) is prepared and ready to upload

Steps​

1. Create the Release on GitLab​

Navigate to the Releases page on GitLab and fill in the following:

Tag name : Use the format YYYY-N where YYYY is the year and N is the release period (1 for January, 2 for July). For example: 2025-1.

Create from : Select the main branch. Ensure the branch contains all the locode data intended for this release.

Release title : Use the format: UN/LOCODE (CODE FOR TRADE AND TRANSPORT LOCATIONS) Issue YYYY-N

Release description : Include the introductory text and a link to the Secretariat Notes. Upload the Secretariat Notes document using the attachment button in the description editor, which will generate a markdown link automatically.

Example description:

1. The UNECE secretariat has the pleasure to introduce herewith UN/LOCODE YYYY-N.
2. UN/LOCODE is available on the Internet, on a site dedicated exclusively
   to the UN/LOCODE https://unlocode.unece.org

Secretariat Release Notes: [YYYY-N_UNLOCODE_SecretariatNotes.doc](/uploads/...)

The page should look something like this:

Release example

2. Publish the Release​

Click Create release. This will:

  1. Create a new Git tag (YYYY-N) pointing at the current main branch
  2. Create the GitLab release with the Secretariat Notes attached

3. Automated Pipeline​

Creating the tag automatically triggers the CI/CD pipeline, which will:

  1. Publish — Generate publication files (CSV, TXT, XML, MDB) from the locode source data
  2. Package — Bundle all publication files into a downloadable archive
  3. Release — Add the Data Archive download link to the existing release
  4. Build Website — Rebuild the website, picking up the new release version and release notes for the Publications page
  5. Deploy — Deploy the updated website

No further action is required from the Secretariat. The pipeline typically completes within a few minutes.

4. Verify​

Once the pipeline completes, verify that:

  • The Publications page shows the new release version with the release notes displayed below the download button
  • The release on GitLab has the UNLOCODE Data Archive asset link attached
  • The data archive downloads correctly

Release Naming Convention​

PeriodTagDisplay Date
First half (January)YYYY-1January YYYY
Second half (July)YYYY-2July YYYY

Troubleshooting​

Pipeline fails on the release job​

If the release was created before the pipeline ran (which is the expected flow), the pipeline will detect the existing release and add the asset link. If the asset link already exists, the job will continue without error.

Release notes not appearing on the website​

The website displays the full release description from GitLab as release notes on the Publications page. Ensure the release has a description with the introductory text and Secretariat Notes link. Any file upload links (e.g., /uploads/...) are automatically resolved to absolute URLs.