diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 6fb012e7..ea157436 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -81,8 +81,8 @@
 /modules/programs/foot.nix                            @plabadens
 /tests/modules/programs/foot                          @plabadens
 
-/modules/programs/gh.nix                              @Gerschtli
-/tests/modules/programs/gh                            @Gerschtli
+/modules/programs/gh.nix                              @Gerschtli @berbiche
+/tests/modules/programs/gh                            @Gerschtli @berbiche
 
 /modules/programs/git.nix                             @rycee
 
diff --git a/modules/programs/gh.nix b/modules/programs/gh.nix
index 4cda4eab..21901999 100644
--- a/modules/programs/gh.nix
+++ b/modules/programs/gh.nix
@@ -6,50 +6,96 @@ let
 
   cfg = config.programs.gh;
 
+  yamlFormat = pkgs.formats.yaml { };
+
+  settingsType = types.submodule {
+    freeformType = yamlFormat.type;
+    # These options are only here for the mkRenamedOptionModule support
+    options = {
+      aliases = mkOption {
+        type = with types; attrsOf str;
+        default = { };
+        example = literalExample ''
+          {
+            co = "pr checkout";
+            pv = "pr view";
+          }
+        '';
+        description = ''
+          Aliases that allow you to create nicknames for gh commands.
+        '';
+      };
+      editor = mkOption {
+        type = types.str;
+        default = "";
+        description = ''
+          The editor that gh should run when creating issues, pull requests, etc.
+          If blank, will refer to environment.
+        '';
+      };
+      git_protocol = mkOption {
+        type = types.str;
+        default = "https";
+        example = "ssh";
+        description = ''
+          The protocol to use when performing Git operations.
+        '';
+      };
+    };
+  };
+
 in {
-  meta.maintainers = [ maintainers.gerschtli ];
+  meta.maintainers = [ maintainers.gerschtli maintainers.berbiche ];
+
+  imports = (map (x:
+    mkRenamedOptionModule [ "programs" "gh" x ] [
+      "programs"
+      "gh"
+      "settings"
+      x
+    ]) [ "aliases" "editor" ]) ++ [
+      (mkRenamedOptionModule [ "programs" "gh" "gitProtocol" ] [
+        "programs"
+        "gh"
+        "settings"
+        "git_protocol"
+      ])
+    ];
 
   options.programs.gh = {
     enable = mkEnableOption "GitHub CLI tool";
 
-    aliases = mkOption {
-      type = with types; attrsOf str;
+    package = mkOption {
+      type = types.package;
+      default = pkgs.gh;
+      defaultText = literalExample "pkgs.gh";
+      description = "Package providing <command>gh</command>.";
+    };
+
+    settings = mkOption {
+      type = settingsType;
       default = { };
+      description =
+        "Configuration written to <filename>$XDG_CONFIG_HOME/gh/config.yml</filename>.";
       example = literalExample ''
         {
-          co = "pr checkout";
-          pv = "pr view";
-        }
-      '';
-      description = ''
-        Aliases that allow you to create nicknames for gh commands.
-      '';
-    };
+          git_protocol = "ssh";
 
-    editor = mkOption {
-      type = types.str;
-      default = "";
-      description = ''
-        The editor that gh should run when creating issues, pull requests, etc.
-        If blank, will refer to environment.
-      '';
-    };
+          prompt = "enabled";
 
-    gitProtocol = mkOption {
-      type = types.enum [ "https" "ssh" ];
-      default = "https";
-      description = ''
-        The protocol to use when performing Git operations.
+          aliases = {
+            co = "pr checkout";
+            pv = "pr view";
+          };
+        };
       '';
     };
   };
 
   config = mkIf cfg.enable {
-    home.packages = [ pkgs.gh ];
+    home.packages = [ cfg.package ];
 
-    xdg.configFile."gh/config.yml".text = builtins.toJSON {
-      inherit (cfg) aliases editor;
-      git_protocol = cfg.gitProtocol;
-    };
+    xdg.configFile."gh/config.yml".source =
+      yamlFormat.generate "gh-config.yml" cfg.settings;
   };
 }
diff --git a/tests/modules/programs/gh/config-file.nix b/tests/modules/programs/gh/config-file.nix
index 432437f9..58600e7f 100644
--- a/tests/modules/programs/gh/config-file.nix
+++ b/tests/modules/programs/gh/config-file.nix
@@ -4,8 +4,8 @@
   config = {
     programs.gh = {
       enable = true;
-      aliases = { co = "pr checkout"; };
-      editor = "vim";
+      settings.aliases = { co = "pr checkout"; };
+      settings.editor = "vim";
     };
 
     test.stubs.gh = { };
@@ -14,7 +14,11 @@
       assertFileExists home-files/.config/gh/config.yml
       assertFileContent home-files/.config/gh/config.yml ${
         builtins.toFile "config-file.yml" ''
-          {"aliases":{"co":"pr checkout"},"editor":"vim","git_protocol":"https"}''
+          aliases:
+            co: pr checkout
+          editor: vim
+          git_protocol: https
+        ''
       }
     '';
   };
diff --git a/tests/modules/programs/gh/default.nix b/tests/modules/programs/gh/default.nix
index 680e8b27..0a915744 100644
--- a/tests/modules/programs/gh/default.nix
+++ b/tests/modules/programs/gh/default.nix
@@ -1 +1,4 @@
-{ gh-config-file = ./config-file.nix; }
+{
+  gh-config-file = ./config-file.nix;
+  gh-warnings = ./warnings.nix;
+}
diff --git a/tests/modules/programs/gh/warnings.nix b/tests/modules/programs/gh/warnings.nix
new file mode 100644
index 00000000..53937a7c
--- /dev/null
+++ b/tests/modules/programs/gh/warnings.nix
@@ -0,0 +1,35 @@
+{ config, options, lib, pkgs, ... }:
+
+{
+  config = {
+    programs.gh = {
+      enable = true;
+      aliases = { co = "pr checkout"; };
+      editor = "vim";
+    };
+
+    test.stubs.gh = { };
+
+    test.asserts.warnings.expected = [
+      "The option `programs.gh.editor' defined in ${
+        lib.showFiles options.programs.gh.editor.files
+      } has been renamed to `programs.gh.settings.editor'."
+      "The option `programs.gh.aliases' defined in ${
+        lib.showFiles options.programs.gh.aliases.files
+      } has been renamed to `programs.gh.settings.aliases'."
+    ];
+    test.asserts.warnings.enable = true;
+
+    nmt.script = ''
+      assertFileExists home-files/.config/gh/config.yml
+      assertFileContent home-files/.config/gh/config.yml ${
+        builtins.toFile "config-file.yml" ''
+          aliases:
+            co: pr checkout
+          editor: vim
+          git_protocol: https
+        ''
+      }
+    '';
+  };
+}