openDesk Hilfe

Contribute to openDesk

Hello, and thank you for considering a contribution to openDesk :star_struck:.

Prerequisites

Before you can contribute to openDesk, please make sure the following prerequisites are in place:

GitLab profile

Please complete your GitLab profile:

  1. In your account settings set/verify your Username, referenced later as <your_username>. You can change it from the default “OCnnnnnnnnnnnn”.
  2. In your profile settings set/verify your Full name is being set, referenced later as <your_full_name> and note your numeric User ID, referenced later as <your_userid>.
  3. Ensure you can provide signed commits, either using SSH or GPG. Documentation on how to add a signing key is available here:

Access to this project

To create a branch in this repository with the related merge request described in the next section, you need Developer access to this project. Access is granted on demand by the CLA bot:

  1. Open a new issue in this project with a title containing the words access followed by request (case-insensitive - for example, Access request).
  2. A scheduled job picks up such issues every 15 minutes. The bot will grant you Developer access to this project and close your issue automatically.
  3. Once your access is in place, continue with the CLA step below.

Note:
The issue description can be left empty — only the title is evaluated.

Contributor License Agreement (CLA)

To be compliant with the project’s requirements you need to sign the Contributor License Agreement (CLA). The CLA clarifies and documents the rights you grant to the openDesk project for your contributions.

The CLA document is at the moment available in two languages:

You can chose between a digital and a classical approach to sign the document.

Digital signature: Use a signed commit

Create a branch and merge request in this repository that adds an entry of the form <your_userid>:<your_username> to the cla-signers.txt file (one signer per line; comment lines start with #). It must be a signed commit and the commit message must match the following example:

git commit --signoff --gpg-sign --message="chore(signers): Add <your_username> (ID: <your_userid>) to signers
 
I, <your_full_name>, acknowledge that I have read, understood, and hereby sign the contributor license agreement in CLA_<de|en>.pdf.
"

In the commit message replace

  • <your_username> with your GitLab Username,
  • <your_userid> with your numeric User ID,
  • <your_full_name> with the (legal) Full name as shown on your national ID card or passport and
  • <de|en> with the two-letter language code of the document that you acknowledge to sign.

Your merge request will be reviewed by the openDesk team as soon as possible and merged once everything matches the description above. Your personal group space will be assigned automatically upon merge.

Classical signature: Send a signed copy by email

Alternatively, you can print the CLA, sign it by hand, scan it, and send it to by email to opendesk@zendis.de

Note:
When using this option the above outlined required details will be added for you to cla-signers.txt .

Contributing

Each contributor who meets the prerequisites above receives a personal group space (initially private) within openDesk’s Contributions group. This is necessary because openCode only provides personal project spaces to members of German public entities.

While openDesk integrates community and supplier artifacts that follow their own contribution processes, you can contribute to openDesk-owned components via openCode. These components are organized into several areas within the base group:

The main repository, in particular, provides detailed guidelines — see the sections below.

Standards and conventions

Please review the project’s workflow documentation for details on standards such as commit message formatting and branching conventions.

Helm vs. Operators vs. Manifests

To align with the Deutsche Verwaltungscloud-Strategie (DVS) and the expectations of DVC platform operators, openDesk follows these packaging conventions:

  • We package components as Helm charts, which may bundle Manifests.
  • We avoid stand-alone Manifests where a Helm chart is more appropriate.
  • We avoid Kubernetes Operators and Custom Resource Definitions (CRDs).

The DVS does not formally prohibit Operators or CRDs, but the relevant specifications strongly favor portable, self-contained delivery artifacts that any DVC platform operator can deploy without granting cluster-scoped permissions or extending the Kubernetes API. In particular:

Avoiding Operators and CRDs keeps openDesk deployable on any compliant DVC platform with namespace-scoped permissions, simplifies certification, and reduces the operational surface that platform operators must support.

To unify the Helm files from the various openDesk components into a single deployment, we use Helmfile.

Tooling

New tools should not be introduced without prior discussion with the team. Proposals are welcome, but the team decides whether a tool will be adopted.

Please help us avoid unnecessary complexity.

In doubt? Open an issue!

Contributions are always welcome. To avoid wasted effort — especially on larger changes — we encourage you to open an issue to discuss your idea and proposed approach beforehand. This is the best way to align your contribution with ongoing work, the overall openDesk platform strategy, and any prior considerations the team may have on the topic.

Note:
Only forks of projects below the openDesk root group are permitted in your personal openDesk Contribution subgroup.

Forks

Once your personal group space has been created, you can create forks within it.

Unfortunately, for forks of projects that contain container images and Helm charts, we cannot enable CI builds of these artifacts in your fork.

Merge Requests

From your forks, you can open merge requests against the upstream repository.

Evidence of testing

Every merge request must document how the change was tested. The openDesk team is responsible for quality assurance and for integrating changes into openDesk, but we cannot do the basic testing of every contribution. Reviewing an untested change often takes more effort than implementing it from scratch, so we will usually not review untested merge requests.

Please include the following in the merge request description:

  • Deployment method: How was the environment deployed (e.g. Helmfile only, GitOps, CI/CD).
  • Environment type: Was the change verified in a dev/test environment or do you use it already in production (near) deployment(s).
  • Environment details: Do you use external services, are there any configurations applied that relate to the provided change.
  • Testing: Which scenarios you exercised and with what result.
  • Not tested: What you deliberately did not test or could not test, e.g. because CI builds of images and charts are not available in your fork.

When necessary, please use the following license and copyright details:

License: Apache-2.0 Copyright: Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH

AI-assisted contributions

This section covers contributions created with the help of AI tools: Coding assistants, chat models and autonomous agents that generate or substantially modify code, tests, configuration or documentation. Syntax-level autocompletion, formatters and linters are not covered.

Like the Linux kernel’s AI Coding Assistants guidelines, we keep a human accountable for every contribution. Like the rest of this document, the section applies to openDesk-owned components. Community and supplier artifacts integrated into openDesk follow their own contribution processes.

Principle

You may use AI tools for your contribution. The person who submits the merge request is responsible for it.

  • An AI tool is never the author or co-author of a contribution.
  • AI-assisted contributions must meet the same requirements for quality, testing, licensing and security as all other contributions.
  • We do not accept contributions that were taken from an AI tool without human review.
  • We do not prescribe specific AI tools or vendors.

Sign-off and disclosure

Sign-offs and commit signatures are your declarations under the CLA. AI tools must not add Signed-off-by trailers or sign commits. You add the sign-off and sign the commit with your own key.

You do not need to disclose AI use and we may rewrite your commit messages anyway when merging to ensure streamlined content of our changelogs. If it helps the reviewer to know which parts were generated, mention it in the merge request description.

Your responsibilities

When you submit an AI-assisted merge request, you are accountable for all of its content as if you had written it yourself.

Understanding

You have read and understood every line. You can explain your design decisions in the review and answer questions without passing them on to an AI tool.

Licensing and provenance

AI tools can reproduce third-party code almost verbatim. Make sure you do not introduce content with unclear or incompatible licensing. Contributions must be compatible with Apache-2.0 and carry correct SPDX headers (see License and Copyright section above). If an AI tool suggests a new dependency, justify and discuss it like any other new dependency or tool (see Tooling).

Security

Check AI-generated code for insecure defaults, missing input validation, overly broad permissions and hard-coded credentials. Pay particular attention to changes affecting authentication, authorization, cryptography and data flows between components.

Testing

The evidence of testing requirements apply in full. “Tested by the AI” or “Tests generated” does not count as evidence. Review AI-generated tests like any other code and check that they test the intended behaviour.

Conventions

Follow the standards and conventions and the packaging conventions described above.

Larger contributions: plan first, code second

For larger changes, please open an issue with your idea and implementation plan before you submit a merge request. This applies especially if you cannot test the change thoroughly.

With AI tools, writing the code is rarely the bottleneck. Most of our effort goes into understanding, reviewing, testing and maintaining a change. For a large AI-generated merge request, that review costs us more than implementing the change ourselves with AI assistance and correcting it as we go. If we agree on a plan first, together, we can fit the change into our architecture, testing and release process from the start.

Larger changes include:

  • new features or components,
  • changes to the architecture or to interfaces between components,
  • changes to security-relevant parts (authentication, permissions, cryptography, data flows) and
  • changes to deployment, the configuration model or upgrade paths.

A good issue describes:

  • the problem or need from a user or operator perspective,
  • the proposed solution and the affected components,
  • risks, alternatives and open questions and
  • optionally, the plan or prompt you would use for the implementation.

Small fixes, documentation improvements and clearly scoped corrections are welcome as direct merge requests.

Handling non-compliant contributions

We may close a merge request without reviewing its content if:

  • the evidence of testing is missing or evidently inaccurate or
  • it contains a larger change that was not discussed beforehand and cannot be reviewed with reasonable effort or
  • the author answers review questions with AI-generated replies and evidently does not understand the change.

In that case we will point you to this section and invite you to propose the idea as an issue.

AI in reviews by the openDesk team

We also use AI tools in reviews, for example for a first assessment, for summaries or as an additional check for errors. A person on the openDesk team always decides whether a contribution is accepted.

Instructions for AI agents

Repositories of openDesk-owned components can contain a short AGENTS.md file with the rules from this section that apply to coding agents. Many agents read it automatically. If you change this section, update the AGENTS.md files as well.