[go: up one dir, main page]
Skip to content

Improve project creation with programmable project templates

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Release notes

Problem to solve

As a Platform Engineer, I want a project bootstrapping method that sets up a new, production-ready, immediately deployable microservice project with all the bells-and-whistles required in my company, so the developers I serve can focus on the business logic.

As a Software Engineer, I want a project creation wizard with a few inputs that results in a new, production-ready, immediately deployable microservice project with all the bells-and-whistles required in my company, so I don't have to learn how to write or edit GitLab pipelines or any other infrastructure and security concepts my company follows, but I can focus on writing the business logic.

The code templates functionality of Backstage provides a great example why our project templates are very much not enough. This functionality is summarized from the platform engineers, adoption point of view in this video: https://youtu.be/TZ6-SpoFVeY?t=474

Current solutions:

  • Use Backstage
  • Use a project management project as described in idea 3 below without any support for such a concept from GitLab.

Proposal

Use pipelines to run automation that results in a fully configure project. In both cases, the project creation consists of the following steps:

  1. pick a template
  2. provide the required and optional inputs
  3. hit submit / run the automation
  4. redirect to the newly configured project

MVC iterations

v1 user story

The platform engineer:

  1. Creates a new, empty project (let's refer to this project as the "wizard project")
  2. Creates a .gitlab/gitlab-wizard.yml and writes a CI component within
  3. Includes the wizard to .gitlab-ci.yml
  4. Registers the project as a group or instance level project template

The Development team lead:

  1. Opens the new project creation page (https://gitlab.com/projects/new)
  2. Selects "Create from template"
  3. Sees the list of templates and wizards (it's a single list as we use the same registration that templates do, but the actions differ)
    • show an "empty state" banner at the top of the list of no wizards are found
  4. The wizards offer two actions:
    1. Learn more: opens the project created by the platform engineer, just like "Preview" does for dumb templates
    2. Use wizard: to be explained in the following steps
  5. Clicks "Use wizard"
  6. GitLab renders a form using the inputs of the CI component defined in .gitlab/gitlab-wizard.yml
  7. User fills out the form
  8. User submits the form by clicking "Run wizard"
  9. GitLab starts a pipeline (actually, the user starts the pipeline) in the wizard project (on the main branch) (pipeline API)
    • caveat: use needs to have at least "Developer" role in the wizard project to kick-off a pipeline
  10. GitLab redirects the user to the pipeline to follow progress

v2 - Auditability

Goal: make usage auditable, support troubleshooting

  • Add syntax to mark an input as sensitive to CI components
    • Not in scope: it might be a good idea to automatically mask the sensitive values in the pipeline; this is out of scope for this issue

Minor changes are made in the Development team lead's experience starting after they hit the "Run wizard" button:

  1. User submits the form by clicking "Run wizard"
  2. GitLab opens an issue in the wizard project with all the details:
    • title: Wizard run by user X at 2024-11-14 13:24
    • description:
      • who started it (gitlab handle + human name)
      • when
      • what were the inputs provided, omit the sensitive attributes
      • what was the git sha of the wizard project
  3. GitLab starts a pipeline (actually, the user starts the pipeline) in the wizard project (on the main branch)
  4. As the pipeline got created, GitLab updates the description of the issue, and appends a link to the pipeline
  5. GitLab redirects the user to the issue created

v3 - Flexible wizard

Goal: enable multi-page wizard forms that take inputs based on other inputs, etc

The platform engineer

  1. Adds .gitlab/gitlab-wizard-form.json to the wizard project
  2. Writes a form definition using JSON forms. It's their responsibility to ensure that the form always ends up with valid inputs for the wizard CI component

The Development team's experience changes when they click "Use wizard":

  1. Clicks "Use wizard"
  2. GitLab renders a form using the JSON forms
  3. User fills out the form

Note: In the end we should be able to generate a form with AND without a .gitlab/gitlab-wizard-form.json being present.

v4 - Remove support for dumb templates

Goal: simplify GitLab by removing superseded features

  1. GitLab creates a CI component that takes a single input (let's call it project_slug), and forks the project where it's run under project_slug
  2. GitLab deprecates the current dumb templates, and recommends users to migrate them to wizards
  3. GitLab changes the "new stuff" ➕ menu (to the left of the user profile image)
    • adds "Run wizard" item under "In GitLab" as the first option
  4. GitLab changes the new project creation page "Create from template" ➡️ "Create with wizard"
  5. Dumb templates remain in the list, but use the "Learn more" and "Use wizard"
  6. When a dumb template is selected (that's better called a wizard without .gitlab/gitlab-wizard.yml) GitLab shows an error page to explain the user how to migrate the template by adding the CI component from step 1, or how to fork the project without keeping the upstream relationship (what dumb templates actually do).

Alternatively, GitLab could do magic and pretend that the CI component from step 1 is to be used, but magic is dangerous. Let's leave magic to wizards!

This approach allows our users to migrate their templates with minimal work, and improve the templates as we can educate them about the feature.

(The attentive reader might have noticed that the wizards are more powerful than just being able to create projects. They allow platform engineers to codify any regularly needed actions into a wizard. That's why we don't call them project wizards, but simply wizards.)

Intended users

Feature Usage Metrics

  • Number of projects created with programmable templates

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by 🤖 GitLab Bot 🤖