Configure your namespace

Purpose of this guide

This guide is meant to give an introduction to the configuration project that is created within each Workshop namespace and controls that namespace's user roles, subgroups, and projects.

What is the Workshop Config project

The Workshop Config project is set up automatically for all Workshop namespaces, and is used by each customer to configure their namespace. It contains data files to control user roles, subgroups, and projects. You can also write custom terraform to control any other aspect of your namespace, as long as those settings are able to be set by a user with owner group permissions.

Why do we have a Workshop Config project

The Workshop Config project lets customers securely configure their namespace by enforcing good defaults for things like user roles and Merge Request approvals. It also helps prevent configuration drift by checking that your settings are still applied as expected each and every night.

How do I update my namespace's configuration

Default process

Updating your configuration is a three step process:

1. Any user with at least the developer role can open a Merge Request against your Workshop Config project in order to update settings or create new projects
2. A namespace owner must review and approve the MR and merge it
3. The provided CI/CD pipeline runs on the main branch and applies your changes

Any additional processes are up to each customer to implement as it makes sense for their use cases.

Delegated process

Optionally, a namespace can be configured so that subgroup owners are responsible for approvals for their own subgroups. See your Workshop Config project README.md file for steps to enable this process.

Once it is enabled, the steps are:

1. Any user with at least the developer role can open a Merge Request against your Workshop Config project in order to update settings or create new projects
2. Either a namespace owner or a subgroup owner must review and approve the MR and merge it, depending on which files have been changed
3. The provided CI/CD pipeline runs on the main branch and applies your changes

Any additional processes are up to each customer to implement as it makes sense for their use cases.

Configuration Options

User roles

There are two places to set user roles for your namespace.

1. The terraform variable namespace_roles set in the settings.auto.tfvars file controls user roles across the entire namespace. These user roles are inherited by all projects and subgroups in the entire namespace
2. Role Membership for each subgroup is specified alongside other subgroup settings in the cg-workshop.yml file

In both cases, users are specified by their GitLab username, not their email address.

Drift notifications

Adding email addresses to the terraform variable config_pipeline_email_notifications will enable notifications when the Workshop Config project's pipeline fails when run against the main branch, including when nightly drift detection fails.

Description template project

A project can be setup to provide Description Templates across your entire namespace. This helps to standardize issues and merge requests out of the box, and can be expanded to provide many common files that are customized to your agency.

The base of these description templates can be:

• workshop - a set of issue templates and merge request templates guided by what the Workshop team uses
• basic - barebones templates to serve as a starting point for your customizations
• none - set up the project and tell GitLab to use it for templates, but does not include any default content

No matter which choice, the templates can be modified to fit your use case by opening Merge Requests in the Namespace File Templates project that was created in your namespace.

Subgroups

Subgroups can be used to partition projects into related sections, or to control developer access more tightly. Each subgroup can define their own role members, in addition to inheriting memberships from parent groups.

note

Subgroups always inherit role memberships from their parent(s), and users will always have the highest permission level they've been granted at the subgroup or its parents.

tip

Subgroups can always be more private than their parent group, but never more public.

Define subgroups within a file called cg-workshop.yml and see example-cg-workshop.yml within your Workshop Config project for more information on available options.

Projects

Projects are the backbone of Workshop. They can hold code, issues, a container registry, and many other items.

Project membership is set in two ways:

1. Membership is always inherited from roles on the project's group hierarchy. For example: members of the group developers role will have developer access to all projects in that group or its subgroups
2. Role groups from other subgroups can be attached directly to a project.

note

Role permissions can be downgraded but not upgraded when attached to a project. This means that you can add a subgroup's owners as developers on a project, but you cannot add a subgroup's reporters as developers.

Users in the latter situation would still have reporter permissions to the project.

tip

Projects can always be more private than the group they are contained in, but never more public.

Define projects within a file called cg-workshop.yml and see example-cg-workshop.yml within your Workshop Config project for more information on available options.

Custom terraform

Any terraform files you add to the root directory of your Workshop Config project will be applied in addition to the settings.auto.tfvars and yaml settings files.

Your terraform files will be able to use the gitlab terraform provider, configured with a token that grants your code Owner permission to your namespace. You must configure and supply credentials for any other providers that you are using.

warning

Do not name your terraform files with a nsc_ prefix, or they risk being overwritten by the workshop-namespace-config CI component that runs the pipeline.

Example Configuration

The following two files will configure a namespace with a couple of namespace-wide users, two subgroups, and four projects, one in the namespace itself and three in the subgroups.

settings.auto.tfvars

# set roles for users in the root namespace and all subgroups
namespace_roles = {
  maintainers = [
    "maintainer.lastname"
  ]
  reporters = [
    "project.reader",
    "compliance.auditor"
  ]
}

# send pipeline failure notifications for the Workshop Config
# project to these two email addresses
config_pipeline_email_notifications = [
  "owner.email@agency.gov",
  "compliance.auditor@agency.gov"
]

# create a description template project based on Workshop defaults
description_template_base = "workshop"

cg-workshop.yml

subgroups:
  system-one:
    name: System ONE
    description: All projects related to System ONE
    # this assumes the overall namespace was made public
    # subgroups and projects cannot be more public than their containing group
    visibility: public
    members:
      owners:
        - system.one.owner
      developers:
        # note that `maintainer.lastname` will have the role of `maintainer`
        # because that is inherited from the namespace level, but they can be added
        # to this group also for ease of @mentioning groups of people
        - maintainer.lastname
        - contractor.one
        - contractor.two
  system-two:
    name: System TWO
    description: All projects related to the successor to System ONE
    visibility: internal
    members:
      owners:
        - system.one.owner
        - system.two.owner
      developers:
        - contractor.two
        - contractor.three
projects:
  # this special project will display its README on the group page
  gitlab-profile:
    name: 0.gitlab-profile
    # this assumes the overall namespace was made public
    # subgroups and projects cannot be more public than their containing group
    visibility: public
    description: Project to hold group README and documentation.
    # Important if your project doesn't use CI pipelines
    only_allow_merge_if_pipeline_succeeds: false

  system-one-api:
    name: System ONE API
    visibility: public
    description: The API powering all of System ONE
    subgroup_key: system-one
    # allow system-two developers to also have development role on just this project
    group_roles:
      developers:
        - system-two/roles/developers

  system-one-compliance:
    name: System ONE compliance documentation
    visibility: private
    description: Repository of compliance documentation and evidence
    only_allow_merge_if_pipeline_succeeds: false
    subgroup_key: system-one

  system-two-api:
    name: System TWO API
    visibility: internal
    description: Next Gen System API
    subgroup_key: system-two

Further reading

• Explore the JSON schema for cg-workshop.yml
• See your config project's README for information on splitting the single cg-workshop.yml file into multiple independent configuration files