feat(ng-dev): create a caretaker config subcommand for updated repo properties

josephperrott · josephperrott · commit e66864cc3c6b · 2025-11-18T22:45:08.000Z
Create a config subcommand to allow for `get` and `set` actions against a defined list of custom properties on angular repositories. These will be used to set the merge mode of the repository being configured.
diff --git a/.github/local-actions/branch-manager/main.js b/.github/local-actions/branch-manager/main.js
diff --git a/ng-dev/caretaker/cli.ts b/ng-dev/caretaker/cli.ts
@@ -11,10 +11,15 @@ import {Argv} from 'yargs';
 import {assertValidCaretakerConfig, assertValidGithubConfig, getConfig} from '../utils/config.js';
 import {CheckModule} from './check/cli.js';
 import {HandoffModule} from './handoff/cli.js';
+import {MergeModeModule} from './merge-mode/cli.js';
 
 /** Build the parser for the caretaker commands. */
 export function buildCaretakerParser(argv: Argv) {
-  return argv.middleware(caretakerCommandCanRun, false).command(CheckModule).command(HandoffModule);
+  return argv
+    .middleware(caretakerCommandCanRun, false)
+    .command(MergeModeModule)
+    .command(CheckModule)
+    .command(HandoffModule);
 }
 
 function caretakerCommandCanRun() {
diff --git a/ng-dev/caretaker/merge-mode/cli.ts b/ng-dev/caretaker/merge-mode/cli.ts
@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Argv, Arguments, CommandModule} from 'yargs';
+import {Log} from '../../utils/logging';
+import {addGithubTokenOption} from '../../utils/git/github-yargs';
+import {setMergeModeRelease} from './release';
+import {resetMergeMode} from './reset';
+import {getCurrentMergeMode} from '../../utils/git/repository-merge-mode';
+
+interface Options {
+  mode?: string;
+}
+
+async function setMergeModeBuilder(argv: Argv): Promise<Argv<Options>> {
+  return addGithubTokenOption(argv).positional('mode', {
+    type: 'string',
+    choices: ['release', 'reset'],
+  });
+}
+
+async function setMergeModeHandler({mode}: Arguments<Options>) {
+  if (mode === undefined) {
+    const currentMode = await getCurrentMergeMode();
+    Log.info(`Repository merge-mode is currently set to: ${currentMode}`);
+    return;
+  }
+  if (mode === 'reset') {
+    return await resetMergeMode();
+  }
+  if (mode === 'release') {
+    return await setMergeModeRelease();
+  }
+  Log.error(`Unable to set the merge mode to the provided mode: ${mode}`);
+}
+
+export const MergeModeModule: CommandModule<{}, {}> = {
+  builder: setMergeModeBuilder,
+  handler: setMergeModeHandler,
+  command: ['merge-mode [mode]'],
+  describe: 'Set the repository merge mode',
+};
diff --git a/ng-dev/caretaker/merge-mode/release.ts b/ng-dev/caretaker/merge-mode/release.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {setRepoMergeMode} from '../../utils/git/repository-merge-mode';
+import {green, Log, red} from '../../utils/logging';
+
+export async function setMergeModeRelease() {
+  try {
+    await setRepoMergeMode('release');
+    Log.info(`${green('✔')} Repository is set for release`);
+  } catch (err) {
+    Log.info(`${red('✘')} Failed to setup of repository for release`);
+    if (err instanceof Error) {
+      Log.info(err.message);
+      Log.debug(err.stack);
+      return;
+    }
+    Log.info(err);
+  }
+}
diff --git a/ng-dev/caretaker/merge-mode/reset.ts b/ng-dev/caretaker/merge-mode/reset.ts
@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {assertValidGithubConfig, getConfig} from '../../utils/config';
+import {setRepoMergeMode} from '../../utils/git/repository-merge-mode';
+import {green, Log, red} from '../../utils/logging';
+
+export async function resetMergeMode() {
+  try {
+    const {
+      github: {mergeMode},
+    } = await getConfig([assertValidGithubConfig]);
+    await setRepoMergeMode(mergeMode);
+    Log.info(`${green('✔')} Repository has been reset to the normal mode: ${mergeMode}`);
+  } catch (err) {
+    Log.info(`${red('✘')} Failed to reset the merge mode of the repository`);
+    if (err instanceof Error) {
+      Log.info(err.message);
+      Log.debug(err.stack);
+      return;
+    }
+    Log.info(err);
+  }
+}
diff --git a/ng-dev/pr/merge/integration.spec.ts b/ng-dev/pr/merge/integration.spec.ts
@@ -35,7 +35,12 @@ describe('default target labels', () => {
 
   beforeEach(() => {
     api = new GithubClient();
-    githubConfig = {owner: 'angular', name: 'dev-infra-test', mainBranchName: 'master'};
+    githubConfig = {
+      mergeMode: 'caretaker-only',
+      owner: 'angular',
+      name: 'dev-infra-test',
+      mainBranchName: 'master',
+    };
     releaseConfig = {
       representativeNpmPackage: '@angular/dev-infra-test-pkg',
       npmPackages: [{name: '@angular/dev-infra-test-pkg'}],
diff --git a/ng-dev/release/notes/changelog.spec.ts b/ng-dev/release/notes/changelog.spec.ts
@@ -12,7 +12,12 @@ describe('Changelog', () => {
   beforeEach(() => {
     cleanTestTmpDir();
     gitClient = getMockGitClient(
-      {owner: 'angular', name: 'dev-infra-test', mainBranchName: 'main'},
+      {
+        mergeMode: 'team-only',
+        owner: 'angular',
+        name: 'dev-infra-test',
+        mainBranchName: 'main',
+      },
       /* useSandboxGitClient */ false,
     );
     spyOn(GitClient, 'get').and.resolveTo(gitClient);
diff --git a/ng-dev/release/publish/test/release-notes/context.spec.ts b/ng-dev/release/publish/test/release-notes/context.spec.ts
@@ -16,6 +16,7 @@ const defaultContextData: RenderContextData = {
   hiddenScopes: undefined,
   groupOrder: undefined,
   github: {
+    mergeMode: 'caretaker-only',
     name: 'repoName',
     owner: 'repoOwner',
     mainBranchName: 'master',
diff --git a/ng-dev/release/publish/test/release-notes/generation.spec.ts b/ng-dev/release/publish/test/release-notes/generation.spec.ts
@@ -33,7 +33,12 @@ describe('release notes generation', () => {
       representativeNpmPackage: 'test-pkg',
       buildPackages: async () => [],
     };
-    githubConfig = {owner: 'angular', name: 'dev-infra-test', mainBranchName: 'main'};
+    githubConfig = {
+      mergeMode: 'caretaker-only',
+      owner: 'angular',
+      name: 'dev-infra-test',
+      mainBranchName: 'main',
+    };
     setConfig({github: githubConfig, release: releaseConfig});
     client = getMockGitClient(githubConfig, /* useSandboxGitClient */ true);
 
diff --git a/ng-dev/release/publish/test/test-utils/action-mocks.ts b/ng-dev/release/publish/test/test-utils/action-mocks.ts
@@ -45,6 +45,7 @@ export const testReleasePackages: NpmPackage[] = [
 /** Gets test configurations for running testing a publish action. */
 export function getTestConfigurationsForAction() {
   const githubConfig: GithubConfig = {
+    mergeMode: 'caretaker-only',
     owner: 'angular',
     name: 'dev-infra-test',
     mainBranchName: 'master',
diff --git a/ng-dev/release/versioning/test/active-release-trains.spec.ts b/ng-dev/release/versioning/test/active-release-trains.spec.ts
@@ -288,7 +288,12 @@ describe('active release train determination', () => {
   let repo: ReleaseRepoWithApi;
 
   beforeEach(() => {
-    setup({owner: 'angular', name: 'dev-infra-test', mainBranchName: 'main'});
+    setup({
+      mergeMode: 'team-only',
+      owner: 'angular',
+      name: 'dev-infra-test',
+      mainBranchName: 'main',
+    });
   });
 
   afterEach(() => nock.cleanAll());
diff --git a/ng-dev/utils/config.ts b/ng-dev/utils/config.ts
@@ -23,6 +23,9 @@ export type NgDevConfig<T = {}> = T & {
   __isNgDevConfigObject: boolean;
 };
 
+/** The available merge modes for repositories to utilize for normal usage. */
+export type RepositoryMergeModes = 'team-only' | 'caretaker-only';
+
 /**
  * Describes the Github configuration for dev-infra. This configuration is
  * used for API requests, determining the upstream remote, etc.
@@ -40,6 +43,11 @@ export interface GithubConfig {
   private?: boolean;
   /** Whether to default to use NgDevService for authentication. */
   useNgDevAuthService?: boolean;
+  /**
+   * The merge mode to use for the repository, either allowing only the caretaker to perform
+   * merges, or allowing all team members to do so.
+   */
+  mergeMode: RepositoryMergeModes;
 }
 
 /** Configuration describing how files are synced into Google. */
@@ -180,6 +188,9 @@ export function assertValidGithubConfig<T extends NgDevConfig>(
     if (config.github.owner === undefined) {
       errors.push(`"github.owner" is not defined`);
     }
+    if (config.github.mergeMode === undefined) {
+      errors.push(`"github.mergeMode" is not defined`);
+    }
   }
   if (errors.length) {
     throw new ConfigValidationError('Invalid `github` configuration', errors);
diff --git a/ng-dev/utils/git/repository-merge-mode.ts b/ng-dev/utils/git/repository-merge-mode.ts
@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright Google LLC
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Log} from '../logging';
+import {AuthenticatedGitClient} from './authenticated-git-client';
+
+const mergeModePropertyName = 'merge-mode';
+
+export async function getCurrentMergeMode() {
+  const git = await AuthenticatedGitClient.get();
+
+  const {data: properties} = await git.github.repos.customPropertiesForReposGetRepositoryValues({
+    owner: git.remoteConfig.owner,
+    repo: git.remoteConfig.name,
+  });
+
+  const property = properties.find(({property_name}) => property_name === mergeModePropertyName);
+  if (property === undefined) {
+    throw Error(`No repository configuration value with the key: ${mergeModePropertyName}`);
+  }
+
+  return property.value;
+}
+
+export async function setRepoMergeMode(value: string) {
+  const currentValue = await getCurrentMergeMode();
+  if (currentValue === value) {
+    Log.debug(
+      'Skipping update of repository configuration value as it is already set to the provided value',
+    );
+    return false;
+  }
+  const git = await AuthenticatedGitClient.get();
+  const {value_type, allowed_values} = await getRepoConfigValueDefinition(
+    mergeModePropertyName,
+    git,
+  );
+
+  if (value_type !== 'single_select') {
+    throw Error(
+      `Unable to update ${mergeModePropertyName} as its type is ${value_type}, currently the ` +
+        `only supported configuration type is single_select`,
+    );
+  }
+
+  if (!allowed_values!.includes(value)) {
+    throw Error(
+      `Unable to update ${mergeModePropertyName}. The value provided must use one of: ` +
+        `${allowed_values!.join(', ')}\nBut "${value}" was provided as the value`,
+    );
+  }
+
+  // All members of the github team, `team` have been assigned the custom role `Custom Property
+  // Editor` allowing their accounts to update the values the custom properties in Angular repos.
+  await git.github.repos.customPropertiesForReposCreateOrUpdateRepositoryValues({
+    owner: git.remoteConfig.owner,
+    repo: git.remoteConfig.name,
+    properties: [
+      {
+        property_name: mergeModePropertyName,
+        value,
+      },
+    ],
+  });
+
+  return true;
+}
+
+async function getRepoConfigValueDefinition(key: string, git: AuthenticatedGitClient) {
+  return git.github.orgs
+    .customPropertiesForReposGetOrganizationDefinition({
+      custom_property_name: key,
+      org: git.remoteConfig.owner,
+    })
+    .then(({data}) => data);
+}
diff --git a/ng-dev/utils/testing/virtual-git-client.ts b/ng-dev/utils/testing/virtual-git-client.ts
@@ -17,6 +17,7 @@ import {GitClient} from '../git/git-client.js';
 /** A mock instance of a configuration for the ng-dev toolset for default testing. */
 export const mockNgDevConfig: {github: GithubConfig} = {
   github: {
+    mergeMode: 'caretaker-only',
     name: 'name',
     owner: 'owner',
     mainBranchName: 'master',
