The publiccode.yml file is a standard format for metadata that can be used to describe open source projekte in the public sector.

On openCode, all entries in the software directory are automatically imported from the respective publiccode.yml files of the projekte on the GitLab instance. Conversely, this means that only projekte that contain a valid publiccode.yml file will appear in the directory.

These instructions are designed to help you create such a publiccode.yml file for your software.

How do I create a working publiccode-yml file?

  1. Open your project on GitLab

  2. Navigate to Repository > Files

  3. Create a new file named publiccode.yml. Use the openCode editor or download this annotated template.

  4. Maintain the basic data: Start with the official schema, such as the name, version of your software, the URL, and appropriate categories. You can find a list of possible entries on the metadata standard page.

  5. Fill in the project description: Explain briefly and clearly what your software project is and illustrate it with meaningful screenshots. Our recommendation: Maintain two languages!

  6. Determine the target audience (countries and subject areas) for the software:

  7. Add license and contact persons: Specify the license under which your project is licensed and where the code is located. The selected license must be on our list of permitted licenses. You should also name a contact person who is responsible for the software.

  8. Check and publish: The easiest way to check your publiccode.yml file is to load it into our openCode Editor and then click on the Validate button. If the file is error-free, nothing stands in the way of publication. After creating the file, your project will automatically appear in the software directory shortly thereafter.

Customizing the display in the openCode software directory

To customize the display of your software in the software directory to best suit your needs, we recommend following the detailed instructions for customizing the display in the software directory in this guide.

Best Practices from the community

The following examples from the community may be useful for you to understand how to create a publiccode.yml file:

Frequently asked questions and problems

Why are my project's logo or screenshots not displayed?

If your project's logo or screenshots are not displayed, this may be due to the following errors:

  • Your logo or screenshots are not yet listed in the publiccode.yml file. Add the file and complete the path name. The logo file must be located in the top-level folder of your project.
  • Add screenshots in the description section under the section for the respective supported language (e.g., en).
  • You may be using an unsupported file format. Valid file formats for logos are: .svg, .svgz, and .png. Valid file formats for screenshots are: .png and .jpg.
  • The path you specified for your logo file is incorrect. Check the path.
How do I find errors in my publiccode.yml file?

The best way to create your publiccode.yml file is to use our publiccode.yml editor.

In the editor, you can display errors in your file either after uploading your publiccode.yml file or after filling in the corresponding fields using the Validate button.