CLI Reference

Frigg provides several CLI commands for managing your GitLab infrastructure. Commands are passed as arguments when running the Frigg backend.

Commands

—apply

Apply Frigg resources to your GitLab instance. Defaults to a dry-run unless DRY_RUN=false is set.

yarn start --apply
yarn start --apply --dry-run=false

—validate

Load all resource files and run validation. Any validation errors are printed to the console.

yarn start --validate

—export-gitlab

Export one or more existing GitLab groups recursively to Frigg resource files. Specify group paths as a comma-separated list.

yarn start --export-gitlab=<group_path,group_path2,...>

For self-managed instances, you can export all groups (including user projects) by omitting the group argument and using the --include-user-projects flag:

yarn start --export-gitlab --include-user-projects

—merge-request-comment

Dry-run apply and post the change list and any validation errors as a comment on the provided merge request. Used in CI/CD pipelines to preview changes before deployment.

yarn start --merge-request-comment=<merge_request_iid>

—export-missing-resources

Check for groups and projects that exist on GitLab but do not have corresponding resource files underneath a root group.

yarn start --export-missing-resources=<root_group_path>

—export-missing-resources-mr

Same as --export-missing-resources, but also creates a merge request with the missing resource files automatically.

yarn start --export-missing-resources-mr=<root_group_path>

Environment variables for this command:

Variable	Default	Description
`MISSING_RESOURCES_REPO_PATH`	`./tmp/repo`	Path to local git repo for missing resources
`MISSING_RESOURCES_BRANCH`	`missing_resources_branch`	Branch name for the changes
`MISSING_RESOURCES_MR_TITLE`	`Add missing resources from GitLab`	Title for the created merge request

—apply-changed-resources

Apply only the resources that have changed compared to the main branch. Useful in combination with the missing resources workflow.

yarn start --apply-changed-resources

—export-audit

Export audit events to daily JSON files. These files are consumed by Frigg Pages to display an audit log.

yarn start --export-audit

Use --include-previous-audit to download and merge audit events from the last pages deployment, ensuring continuity:

yarn start --export-audit --include-previous-audit

—export-auth-matrix

Export the authorization matrix to matrix-users.json and matrix-groups.json. These files are consumed by Frigg Pages to display authorization matrix views.

yarn start --export-auth-matrix

Requires the GITLAB_BASE_GROUP environment variable to be set. For self-managed instances managing the root, use /.

Environment Variables

Required

Variable	Description
`GITLAB_FRIGG_PROJECT`	Short GitLab ID of the Frigg project. Used for state persistence and MR comment placement.
`GITLAB_TOKEN`	Access token with owner role (SaaS) or admin permissions (self-managed) on the managed groups.

Optional

Variable	Default	Description
`GITLAB_URL`	`https://gitlab.com`	URL of your GitLab instance
`RESOURCES_PATH`	`./resources`	Path to the base folder with your resource files
`DRY_RUN`	`true`	Set to `false` to execute changes. Used with `--apply`.
`REQUEST_TIMEOUT`	`20000`	Global request timeout in milliseconds
`RATE_LIMIT`	`300`	Request rate limit in requests per second
`QUERY_TIMEOUT`	`300000`	Timeout for bundled queries in milliseconds
`STATIC_PAGE_TIMEOUT`	`60`	Timeout for GitLab Pages generation in seconds
`MAX_CONNECTIONS`	unlimited	Maximum number of connections Frigg can open to the GitLab API
`CONCURRENCY_LIMIT`	`10`	Maximum number of concurrent GitLab API operations
`COUNT_API_CALLS`	`false`	Set to `true` to enable API call counting and display total at end

CI/CD Integration

For a complete CI/CD pipeline example including validate, deploy, and pages stages, see the Setup Frigg with Docker guide.

To add audit log and authorization matrix generation to your pipeline, add these jobs:

export-audit:
    stage: deploy
    image:
        name: $FRIGG_REGISTRY/frigg-backend:$FRIGG_BACKEND_VERSION
        entrypoint: ['']
    before_script:
        - cd /app
    script:
        - yarn start --export-audit --include-previous-audit
    artifacts:
        paths:
            - audit/
    needs:
        - deploy
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
 
export-auth-matrix:
    stage: deploy
    image:
        name: $FRIGG_REGISTRY/frigg-backend:$FRIGG_BACKEND_VERSION
        entrypoint: ['']
    before_script:
        - cd /app
    script:
        - yarn start --export-auth-matrix
    artifacts:
        paths:
            - matrix-users.json
            - matrix-groups.json
    needs:
        - deploy
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH

Handling Errors Create a project