GitlabProject

The GitlabProject resource allows you to manage GitLab projects declaratively using Frigg.

Schema Reference

GitlabProjectResource

Property	Type	Required	Description
version	string	Yes	Version of Frigg to use. Should be `1`.
kind	`GitlabProject`	Yes	Kind of resource you want to specify
metadata	object	Yes	Data used by Frigg internally
metadata.name	string	Yes	Name used to reference this resource from other resources
metadata.configDefaults	string	Yes	Name of the GitlabDefaults resource to use to resolve default configuration.
metadata.id	number	No	Numeric ID of the GitLab project. Specify this when you want to start managing an already existing project using Frigg.
spec	object	Yes	State you want the resource to have
spec.name	string	Yes	Name of the project in GitLab
spec.groupNamespace	string	No*	Name of the parent group (*must have either groupNamespace or userNamespace)
spec.userNamespace	string	No*	Name of the user in whose namespace the project is in (*must have either groupNamespace or userNamespace)
spec.config	GitlabProjectConfig	No	Project configuration. Leave undefined to fully use `configDefaults.projectConfig`.
spec.approvalsConfig	GitlabApprovalsConfig	No	Approval configuration. Leave undefined to fully use `configDefaults.approvalsConfig`.
spec.approvalRules	GitlabApprovalRule array	No	Approval rules for merge requests. Leave undefined to fully use `configDefaults.approvalRules`.
spec.pushRules	GitlabPushRule	No	Push rules for commits. Leave undefined to fully use `configDefaults.pushRules`.
spec.protectedBranches	GitlabProtectedBranch array	No	Protected branch configurations. Leave undefined to fully use `configDefaults.protectedBranches`.
spec.manageMembers	boolean	No	Whether Frigg should manage member access. When true, only members specified in `spec.members` will have access.
spec.members	GitlabMember array	No	Direct members of the project. Only used when `manageMembers` is true.
spec.sharedWithGroups	SharedWithGroup array	No	Groups that this project is shared with, granting all group members access.

Namespace Selection Guide

You must specify either groupNamespace or userNamespace, but not both:

Use Case	Namespace Type	Example
Team or organizational projects	groupNamespace	`groupNamespace: my_team`
Personal or individual projects	userNamespace	`userNamespace: john.doe`

Configuration Details

GitlabProjectConfig

All properties are optional. Any undefined properties will default to the specified configDefaults.projectConfig of the referenced GitlabDefaults.

Required Configuration Properties

Most projects will want to configure these essential properties:

Property	Type	Default	Description
defaultBranch	string	`main`	The default branch for the project
visibility	`public` \| `internal` \| `private`	`private`	Project visibility level
mergeMethod	`merge` \| `rebase_merge` \| `ff`	`merge`	Merge request merge strategy
removeSourceBranchAfterMerge	boolean	`false`	Automatically delete source branch after merge

CI/CD Configuration

Property	Type	Description
ciConfigPath	string	Path to CI configuration file (default: `.gitlab-ci.yml`)
ciDefaultGitDepth	number	Git depth for CI clones (0 = full clone, default: 20)
autoCancelPendingPipelines	`enabled` \| `disabled`	Cancel older pipelines when new one starts
ciAllowForkPipelinesToRunInParentProject	boolean	Allow fork pipelines to access parent project CI/CD variables
ciForwardDeploymentEnabled	boolean	Prevent older deployments to same environment
ciSeparatedCaches	boolean	Use separate caches for protected/non-protected branches
mergePipelinesEnabled	boolean	Enable merged results pipelines
mergeTrainsEnabled	boolean	Enable merge trains
onlyAllowMergeIfPipelineSucceeds	boolean	Require pipeline success before merge
allowMergeOnSkippedPipeline	boolean	Allow merge when pipeline is skipped
allowPipelineTriggerApproveDeployment	boolean	Allow pipeline triggers to approve deployments
autoDevopsEnabled	boolean	Enable Auto DevOps
autoDevopsDeployStrategy	`continuous` \| `manual` \| `timed_incremental`	Auto DevOps deployment strategy
buildGitStrategy	string	Git strategy for builds (`fetch` or `clone`)
buildTimeout	number	Maximum build time in seconds (default: 3600)
keepLatestArtifact	boolean	Keep artifacts from latest successful pipeline
restrictUserDefinedVariables	boolean	Restrict use of user-defined CI/CD variables to maintainers
sharedRunnersEnabled	boolean	Enable shared runners for this project
groupRunnersEnabled	boolean	Enable group runners for this project

Merge Request Configuration

Property	Type	Description
onlyAllowMergeIfAllDiscussionsAreResolved	boolean	Require all discussions resolved before merge
squashOption	`never` \| `always` \| `default_on` \| `default_off`	Squash commits behavior
mergeCommitTemplate	string	Template for merge commit messages
squashCommitTemplate	string	Template for squash commit messages
mergeRequestsTemplate	string	Template for new merge request descriptions
suggestionCommitMessage	string	Template for suggestion commit messages
resolveOutdatedDiffDiscussions	boolean	Automatically resolve outdated diff discussions
printingMergeRequestLinkEnabled	boolean	Print merge request link after push

Access Level Configuration

Configure feature access with these levels: disabled (feature unavailable), private (accessible only to project members), enabled (accessible based on project visibility).

Property	Type	Description
issuesAccessLevel	`disabled` \| `private` \| `enabled`	Issues feature access
repositoryAccessLevel	`disabled` \| `private` \| `enabled`	Repository access
mergeRequestsAccessLevel	`disabled` \| `private` \| `enabled`	Merge requests feature access
forkingAccessLevel	`disabled` \| `private` \| `enabled`	Ability to fork the project
wikiAccessLevel	`disabled` \| `private` \| `enabled`	Wiki feature access
snippetsAccessLevel	`disabled` \| `private` \| `enabled`	Snippets feature access
buildsAccessLevel	`disabled` \| `private` \| `enabled`	CI/CD pipelines and jobs access
analyticsAccessLevel	`disabled` \| `private` \| `enabled`	Analytics features access
containerRegistryAccessLevel	`disabled` \| `private` \| `enabled`	Container registry access
securityAndComplianceAccessLevel	`disabled` \| `private` \| `enabled`	Security and compliance features access
releasesAccessLevel	`disabled` \| `private` \| `enabled`	Releases feature access
infrastructureAccessLevel	`disabled` \| `private` \| `enabled`	Infrastructure feature access
featureFlagsAccessLevel	`disabled` \| `private` \| `enabled`	Feature flags access
monitorAccessLevel	`disabled` \| `private` \| `enabled`	Monitoring features access
requirementsAccessLevel	`disabled` \| `private` \| `enabled`	Requirements management access
pagesAccessLevel	`disabled` \| `private` \| `enabled` \| `public`	GitLab Pages access (public allows external access)

Additional Configuration

Property	Type	Description
description	string	Project description
topics	string[]	Project topics/tags for categorization
lfsEnabled	boolean	Enable Git LFS
requestAccessEnabled	boolean	Allow users to request access
emailsEnabled	boolean	Enable email notifications
packagesEnabled	boolean	Enable package registry
serviceDeskEnabled	boolean	Enable service desk for external issue creation
autocloseReferencedIssues	boolean	Auto-close issues referenced in merged merge requests
issueBranchTemplate	string	Template for creating branches from issues
issuesTemplate	string	Template for new issue descriptions
mirror	boolean	Enable repository mirroring
enforceAuthChecksOnUploads	boolean	Enforce authentication on uploads
externalAuthorizationClassificationLabel	string	External authorization classification label
containerExpirationPolicyAttributes	object	Container registry cleanup policy configuration

Container Expiration Policy

Configure automatic cleanup of container registry images:

containerExpirationPolicyAttributes:
    enabled: true                      # Enable cleanup policy
    cadence: 1d                        # How often to run (1d, 7d, 14d, 1month, 3month)
    keepN: 10                          # Number of tags to keep
    olderThan: 90d                     # Delete tags older than this (7d, 14d, 30d, 90d)
    nameRegexDelete: .*                # Regex for tags to delete (default: all)
    nameRegexKeep: ''                  # Regex for tags to keep (overrides delete)

GitlabApprovalsConfig

Configuration for merge request approval behavior. All properties are optional and inherit from configDefaults.approvalsConfig when undefined.

Property	Type	Default	Description
resetApprovalsOnPush	boolean	`true`	Reset approvals when new commits are pushed
disableOverridingApproversPerMergeRequest	boolean	`false`	Prevent changing approvers per merge request
mergeRequestsAuthorApproval	boolean	`false`	Allow merge request authors to approve their own merge requests
mergeRequestsDisableCommittersApproval	boolean	`false`	Prevent commit authors from approving merge requests
requirePasswordToApprove	boolean	`false`	Require password confirmation for approvals

Example

The following example includes all possible properties for GitlabProjectConfig and GitlabApprovalsConfig. Furthermore, an example GitlabApprovalRule array is included.

version: '1'
kind: GitlabProject
metadata:
    name: example_project
    configDefaults: GitlabDefaults
spec:
    name: Example Project
    groupNamespace: example_group
    userNamespace: example_user
    config:
        allowMergeOnSkippedPipeline: false
        allowPipelineTriggerApproveDeployment: false
        analyticsAccessLevel: enabled
        autoCancelPendingPipelines: enabled
        autoDevopsDeployStrategy: continuous
        autoDevopsEnabled: false
        autocloseReferencedIssues: true
        buildGitStrategy: fetch
        buildTimeout: 3600
        buildsAccessLevel: enabled
        ciAllowForkPipelinesToRunInParentProject: true
        ciConfigPath: ''
        ciDefaultGitDepth: 20
        ciForwardDeploymentEnabled: true
        ciSeparatedCaches: true
        containerExpirationPolicyAttributes:
            cadence: 1d
            enabled: false
            keepN: 10
            nameRegexDelete: .*
            nameRegexKeep: ''
            olderThan: 90d
        containerRegistryAccessLevel: enabled
        defaultBranch: main
        description: ''
        emailsEnabled: false
        enforceAuthChecksOnUploads: true
        externalAuthorizationClassificationLabel: ''
        featureFlagsAccessLevel: enabled
        forkingAccessLevel: enabled
        groupRunnersEnabled: true
        infrastructureAccessLevel: enabled
        issueBranchTemplate: ''
        issuesAccessLevel: enabled
        issuesTemplate: ''
        keepLatestArtifact: true
        lfsEnabled: true
        mergeCommitTemplate: ''
        mergeMethod: ff
        mergePipelinesEnabled: true
        mergeRequestsAccessLevel: private
        mergeRequestsTemplate: ''
        mergeTrainsEnabled: false
        mirror: false
        monitorAccessLevel: enabled
        onlyAllowMergeIfAllDiscussionsAreResolved: true
        onlyAllowMergeIfPipelineSucceeds: true
        packagesEnabled: true
        pagesAccessLevel: private
        printingMergeRequestLinkEnabled: true
        releasesAccessLevel: enabled
        removeSourceBranchAfterMerge: true
        repositoryAccessLevel: enabled
        requestAccessEnabled: false
        requirementsAccessLevel: enabled
        resolveOutdatedDiffDiscussions: false
        restrictUserDefinedVariables: false
        securityAndComplianceAccessLevel: private
        serviceDeskEnabled: true
        sharedRunnersEnabled: true
        snippetsAccessLevel: disabled
        squashCommitTemplate: ''
        squashOption: default_off
        suggestionCommitMessage: ''
        topics: []
        visibility: private
        wikiAccessLevel: disabled
    approvalsConfig:
        disableOverridingApproversPerMergeRequest: false
        mergeRequestsAuthorApproval: false
        mergeRequestsDisableCommittersApproval: false
        requirePasswordToApprove: false
        resetApprovalsOnPush: true
    approvalRules:
        - name: Approval rule
          appliesToAllProtectedBranches: false
          approvalsRequired: 1
          groupIds: []
          protectedBranchIds: []
          ruleType: any_approver
          usernames: []
    protectedBranches:
        - name: main
          allowForcePush: false
          codeOwnerApprovalRequired: false
          mergeAccessLevels:
              - maintainer
          pushAccessLevels:
              - maintainer
          unprotectedAccessLevels: []
    members:
        - name: alice.johnson
          accessLevel: maintainer
        - name: erik.klein
          accessLevel: developer
    sharedWithGroups:
        - name: another_example_group
          accessLevel: developer

Required Resources

GitlabDefaults - Define default configurations for projects

Sub-Resources

GitlabApprovalRule - Configure merge request approval rules
GitlabPushRule - Configure commit push rules
GitlabProtectedBranch - Configure protected branch access
GitlabMember - Manage direct project members
SharedWithGroup - Share project with groups

GitlabGroup - Manage GitLab groups that can contain projects
GitlabUser - Manage GitLab users

External Documentation

GitlabGroup Users