How-To's

Introducing Space Code Owners

Introducing Code Owners to Space

When you are working on a project, how do you know who is the best person to review or approve your merge request? Who should you ask for more information about a specific file?

In Space, there are a number of ways to find out. The responsibility list will show you broader responsibilities in a project. Annotating files in the history may help too, and, of course, you can always ask people in the team directly while browsing source code in Space.

Today, we’re adding the ability to define who owns specific paths or files in a Git repository using a CODEOWNERS file. It can be used by project members to find out who to contact if you have a question about specific parts of the codebase. In merge requests, the CODEOWNERS file can be used to determine who should review changes.

In this post, we will see how to define code owners and configure CODEOWNERS files with branch protection and quality gates in Space.

Defining code owners

The CODEOWNERS file is part of your Git repository, and outlines who owns certain paths or files in a repository. You can create the CODEOWNERS file in two places:

  • In the root directory of your repository
  • In the .space/ directory

When you create a new repository in Space, a default CODEOWNERS file is created automatically for you. In existing repositories, you can create the file manually. Here’s an example:

# Each line represents a rule, followed by a list of members.
# These members are the default owners for all files
#   that match the specified pattern.
# The pattern generally follows the same syntax used for
#   .gitignore files.
# The last matching rule always wins; those that appear
#   lower in the file  take precedence over rules that
#   appear higher up.
# Specify owners by their username, email,
#   or role assignment in the project.

# Examples:

# Member with username "john.smith" and member
#   with email "alex@mycompany.com" own any JavaScript file
#   in the repository
*.js john.smith alex@mycompany.com

# Bob owns all files under "subdir" directory at the repository
#   root and all its subdirectories
/subdir/ Bob

# All members who are assigned the Project Collaborator role
#   own any file under docs/ directory anywhere in the repository,
#   but not further nested files
docs/* "Project Collaborator"

# This file itself is owned by members who are assigned
#   the Project Admin role in this project.
CODEOWNERS "Project Admin"

Paths can be added in a similar way to how you would add them in .gitignore. Wildcards like docs/ are supported, as are glob patterns like docs/**/*.md.

Owners can be specified as Space usernames, verified email addresses, or roles in the project. You’ll notice in the example that the CODEOWNERS file itself is owned by team members in the Project Admin role.

Order is important. Rules are processed from top to bottom, so that the last matching pattern takes precedence. We recommend adding more general rules at the top of the file, and more specific ones towards the end. In the example file above, any file under /subdir/ will require approval by “Bob”, even if it’s a *.js file that is owned by “John Smith” and “Alex”.

In the Space editor, CODEOWNERS is highlighted to make it easier to read:

Highlighting in the Space editor

The CODEOWNERS file is branch-specific. When you work on a feature branch and update the CODEOWNERS, the main branch will not be updated until after the feature branch is merged. When a merge request is opened against a feature branch, the CODEOWNERS file from that branch applies, if it exists and is configured in a quality gate.

Keep in mind that when the repository contents or structure are updated, or when members join or leave the project, the CODEOWNERS will have to be updated.

Code owner quality gates in merge requests

In your project, you may already be using quality gates in merge requests. Let’s quickly recap what they are.

A quality gate is a set of conditions that need to be met before you can merge your commit into a protected branch such as the main branch or a release branch. Quality gates can be configured for every Git repository in Space. They can be code review approvals, successfully completed Automation jobs, external checks, and the new CODEOWNERS, of course!

The CODEOWNERS quality gate can be enabled in the repository settings, under Protected Branches. When creating a branch protection rule, make sure to regulate the push action — if you allow all committers to push to this branch, the CODEOWNERS approval requirement will not be very useful.

Configure code owners quality gate

When CODEOWNERS is enabled as a quality gate, a code owner for each owned file has to approve changes before you’ll be able to merge a merge request. When approval is required, you will see that merging is not yet possible.

Code owners branch protection in action

Note that when you edit files that are owned by you, Space will pre-approve those changes in your merge request.

We hope CODEOWNERS helps make your code review process more effective. Feel free to comment and ask questions and, of course, give them a try!

image description