Place GitLab into a read-only state

Tier: Free, Premium, Ultimate Offering: Self-managed
note
In GitLab 13.9 and later, the recommended method to place GitLab in a read-only state is to enable maintenance mode.

In some cases, you might want to place GitLab under a read-only state. The configuration for doing so depends on your desired outcome.

Make the repositories read-only

The first thing you want to accomplish is to ensure that no changes can be made to your repositories. There’s two ways you can accomplish that:

  • Either stop Puma to make the internal API unreachable:

    sudo gitlab-ctl stop puma
    
  • Or, open up a Rails console:

    sudo gitlab-rails console
    

    And set the repositories for all projects read-only:

    Project.all.find_each { |project| project.update!(repository_read_only: true) }
    

    When you’re ready to revert this, you can do so with the following command:

    Project.all.find_each { |project| project.update!(repository_read_only: false) }
    

Shut down the GitLab UI

If you don’t mind shutting down the GitLab UI, then the easiest approach is to stop sidekiq and puma, and you effectively ensure that no changes can be made to GitLab:

sudo gitlab-ctl stop sidekiq
sudo gitlab-ctl stop puma

When you’re ready to revert this:

sudo gitlab-ctl start sidekiq
sudo gitlab-ctl start puma

Make the database read-only

If you want to allow users to use the GitLab UI, ensure that the database is read-only:

  1. Take a GitLab backup in case things don’t go as expected.
  2. Enter PostgreSQL on the console as an administrator user:

    sudo \
        -u gitlab-psql /opt/gitlab/embedded/bin/psql \
        -h /var/opt/gitlab/postgresql gitlabhq_production
    
  3. Create the gitlab_read_only user. The password is set to mypassword, change that to your liking:

    -- NOTE: Use the password defined earlier
    CREATE USER gitlab_read_only WITH password 'mypassword';
    GRANT CONNECT ON DATABASE gitlabhq_production to gitlab_read_only;
    GRANT USAGE ON SCHEMA public TO gitlab_read_only;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO gitlab_read_only;
    GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO gitlab_read_only;
    
    -- Tables created by "gitlab" should be made read-only for "gitlab_read_only"
    -- automatically.
    ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON TABLES TO gitlab_read_only;
    ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON SEQUENCES TO gitlab_read_only;
    
  4. Get the hashed password of the gitlab_read_only user and copy the result:

    sudo gitlab-ctl pg-password-md5 gitlab_read_only
    
  5. Edit /etc/gitlab/gitlab.rb and add the password from the previous step:

    postgresql['sql_user_password'] = 'a2e20f823772650f039284619ab6f239'
    postgresql['sql_user'] = "gitlab_read_only"
    
  6. Reconfigure GitLab and restart PostgreSQL:

    sudo gitlab-ctl reconfigure
    sudo gitlab-ctl restart postgresql
    

When you’re ready to revert the read-only state, remove the added lines in /etc/gitlab/gitlab.rb, and reconfigure GitLab and restart PostgreSQL:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

After you verify all works as expected, remove the gitlab_read_only user from the database.