github-settings-as-code 3.0.2 → 3.2.0

package/src/github/constants.mts

@@ -25,6 +25,13 @@ export const actionsSettingsDir = path.resolve(
 
 export const pagesSettingsDir = path.resolve(settingsDir, './pages');
 
+export const environmentsDir = path.resolve(settingsDir, './environments');
+
+export const vulnerabilityAlertsDir = path.resolve(
+  settingsDir,
+  './vulnerability-alerts',
+);
+
 export const rulesetsDir = path.resolve(settingsDir, './rulesets');
 
 export const octokitHeaders = {

package/src/github/environments/api/get-environments.mts

@@ -0,0 +1,155 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { Arr } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { Result } from 'ts-repo-utils';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { EnvironmentSettings } from '../constants.mjs';
+
+/**
+ * Settings > Environments の現在値を、宣言ファイルと同じ形にして返す。
+ *
+ * 名前順に整える。 GitHub が返す順は作成順で、環境を 1 つ足しただけで
+ * `bk/` の中身が並び替わると差分が読めなくなるため。
+ */
+export const getAllEnvironments = async (): Promise<
+  readonly EnvironmentSettings[]
+> => {
+  // https://docs.github.com/rest/deployments/environments#list-environments
+  //
+  // per_page の上限。環境は数個しか無く、 2 ページ目が要る状況は
+  // 「 GUI で何かが大量に作られた」ときだけなので、ページングは張らない。
+  const response = await octokit.request(
+    'GET /repos/{owner}/{repo}/environments' satisfies EndpointKeys,
+    { owner: OWNER, repo: REPO, headers: octokitHeaders, per_page: 100 },
+  );
+
+  const environments = response.data.environments ?? [];
+
+  const settings = await Promise.all(
+    environments.map(async (environment) => {
+      const policy = environment.deployment_branch_policy ?? undefined;
+
+      return EnvironmentSettings.fill({
+        name: environment.name,
+        ...parseProtectionRules(environment.protection_rules),
+        deployment_branch_policy:
+          policy === undefined
+            ? null
+            : {
+                protected_branches: policy.protected_branches,
+                custom_branch_policies: policy.custom_branch_policies,
+              },
+        deployment_branch_policies:
+          policy?.custom_branch_policies === true
+            ? await getDeploymentBranchPolicyNames(environment.name)
+            : [],
+      });
+    }),
+  );
+
+  return settings.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+/** 宣言ファイルに載る形。 `id` は GitHub 側の都合なので落とす。 */
+const getDeploymentBranchPolicyNames = async (
+  environmentName: string,
+): Promise<readonly Readonly<{ name: string; type: 'branch' | 'tag' }>[]> => {
+  const policies = await getDeploymentBranchPolicies(environmentName);
+
+  return policies.map(({ name, type }) => ({ name, type }));
+};
+
+/** 「 Selected branches and tags 」に登録されている pattern を列挙する。 */
+export const getDeploymentBranchPolicies = async (
+  environmentName: string,
+): Promise<readonly DeploymentBranchPolicy[]> => {
+  // https://docs.github.com/rest/deployments/branch-policies#list-deployment-branch-policies
+  const response = await octokit.request(
+    'GET /repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies' satisfies EndpointKeys,
+    {
+      owner: OWNER,
+      repo: REPO,
+      environment_name: environmentName,
+      headers: octokitHeaders,
+      per_page: 100,
+    },
+  );
+
+  return response.data.branch_policies.map((policy) => ({
+    id: policy.id ?? 0,
+    name: policy.name ?? '',
+    type: policy.type === 'tag' ? 'tag' : 'branch',
+  }));
+};
+
+export type DeploymentBranchPolicy = Readonly<{
+  id: number;
+  name: string;
+  type: 'branch' | 'tag';
+}>;
+
+/**
+ * GET が返す `protection_rules` を PUT の body の形に戻す。
+ *
+ * GitHub は有効な保護ルールだけを配列で返し、その要素の `type` は openapi の
+ * 型定義では素の `string` — つまり判別可能 union になっていないので、絞り込みが
+ * 効かない。実データを ts-fortress で読み直すほうが、上流の型に合わせて
+ * キャストを書くより素直で、形が変わったときに黙って通り過ぎることもない。
+ */
+const parseProtectionRules = (
+  protectionRules: unknown,
+): Readonly<{
+  wait_timer: number;
+  prevent_self_review: boolean;
+  reviewers: readonly Readonly<{ type: 'User' | 'Team'; id: number }>[];
+}> => {
+  const validationResult = ProtectionRules.validate(protectionRules ?? []);
+
+  if (Result.isErr(validationResult)) {
+    throw new Error(
+      Arr.toUnshifted(
+        'GitHub が返した environment の protection_rules を読めませんでした。',
+      )(t.validationErrorsToMessages(validationResult.value)).join('\n'),
+    );
+  }
+
+  const rules = validationResult.value;
+
+  const waitTimer = rules.find((rule) => rule.type === 'wait_timer');
+
+  const requiredReviewers = rules.find(
+    (rule) => rule.type === 'required_reviewers',
+  );
+
+  return {
+    wait_timer: waitTimer?.wait_timer ?? 0,
+    prevent_self_review: requiredReviewers?.prevent_self_review ?? false,
+    reviewers: (requiredReviewers?.reviewers ?? []).map((entry) => ({
+      type: entry.type,
+      id: entry.reviewer.id,
+    })),
+  };
+};
+
+const ProtectionRules = t.array(
+  t.record({
+    type: t.string(''),
+    wait_timer: t.optional(t.number(0)),
+    prevent_self_review: t.optional(t.boolean(false)),
+    reviewers: t.optional(
+      t.array(
+        t.record({
+          type: t.enumType(['User', 'Team'], {
+            typeName: 'EnvironmentReviewerType',
+            defaultValue: 'User',
+          }),
+          // `reviewer` は User / Team の完全な表現だが、書き戻しに要るのは id
+          // だけ。 record は既定で余剰キーを通すので、残りはそのまま無視される。
+          reviewer: t.record({ id: t.number(0) }),
+        }),
+      ),
+    ),
+  }),
+  { typeName: 'EnvironmentProtectionRules' },
+);

package/src/github/environments/api/index.mts

@@ -0,0 +1,2 @@
+export * from './get-environments.mjs';
+export * from './set-environment.mjs';

package/src/github/environments/api/set-environment.mts

@@ -0,0 +1,106 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { type EnvironmentSettings } from '../constants.mjs';
+import { getDeploymentBranchPolicies } from './get-environments.mjs';
+
+/**
+ * 環境を JSON の内容に合わせる。無ければ作られる。
+ *
+ * `PUT` は保護ルールを丸ごと置き換えるので、省いたキーは「変更しない」ではなく
+ * 「無効にする」になる。宣言ファイルをそのまま渡しているのはそのため —
+ * 部分更新にすると、ファイルから消した設定が GitHub 側に残る。
+ */
+export const setEnvironment = async (
+  settings: EnvironmentSettings,
+): Promise<void> => {
+  // https://docs.github.com/rest/deployments/environments#create-or-update-an-environment
+  await octokit.request(
+    'PUT /repos/{owner}/{repo}/environments/{environment_name}' satisfies EndpointKeys,
+    {
+      owner: OWNER,
+      repo: REPO,
+      environment_name: settings.name,
+      headers: octokitHeaders,
+      wait_timer: settings.wait_timer,
+      prevent_self_review: settings.prevent_self_review,
+      reviewers: settings.reviewers.map((reviewer) => ({
+        type: reviewer.type,
+        id: reviewer.id,
+      })),
+      deployment_branch_policy:
+        settings.deployment_branch_policy === null
+          ? null
+          : {
+              protected_branches:
+                settings.deployment_branch_policy.protected_branches,
+              custom_branch_policies:
+                settings.deployment_branch_policy.custom_branch_policies,
+            },
+    },
+  );
+
+  await setDeploymentBranchPolicies(settings);
+};
+
+/**
+ * 「 Selected branches and tags 」の pattern を宣言に合わせる。
+ *
+ * 個別の追加・削除しか無いエンドポイントなので、現在値との差分を取って埋める。
+ * 名前と種別が一致するものは触らない — 消して作り直すと id が変わり、
+ * その間だけ deploy できない ref ができる。
+ */
+const keyOf = (policy: Readonly<{ name: string; type: string }>): string =>
+  `${policy.type}:${policy.name}` as const;
+
+const setDeploymentBranchPolicies = async (
+  settings: EnvironmentSettings,
+): Promise<void> => {
+  if (settings.deployment_branch_policy?.custom_branch_policies !== true) {
+    // 選択されていないなら pattern は存在し得ない。 PUT 側が既に消している。
+    return;
+  }
+
+  const current = await getDeploymentBranchPolicies(settings.name);
+
+  const desiredKeys: ReadonlySet<string> = new Set(
+    settings.deployment_branch_policies.map(keyOf),
+  );
+
+  const currentKeys: ReadonlySet<string> = new Set(current.map(keyOf));
+
+  const toDelete = current.filter((p) => !desiredKeys.has(keyOf(p)));
+
+  const toCreate = settings.deployment_branch_policies.filter(
+    (p) => !currentKeys.has(keyOf(p)),
+  );
+
+  for (const policy of toDelete) {
+    // https://docs.github.com/rest/deployments/branch-policies#delete-a-deployment-branch-policy
+    await octokit.request(
+      'DELETE /repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}' satisfies EndpointKeys,
+      {
+        owner: OWNER,
+        repo: REPO,
+        environment_name: settings.name,
+        branch_policy_id: policy.id,
+        headers: octokitHeaders,
+      },
+    );
+  }
+
+  for (const policy of toCreate) {
+    // https://docs.github.com/rest/deployments/branch-policies#create-a-deployment-branch-policy
+    await octokit.request(
+      'POST /repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies' satisfies EndpointKeys,
+      {
+        owner: OWNER,
+        repo: REPO,
+        environment_name: settings.name,
+        headers: octokitHeaders,
+        name: policy.name,
+        type: policy.type,
+      },
+    );
+  }
+};

package/src/github/environments/apply.mts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { Arr } from 'ts-data-forge';
+import { isDirectlyExecuted } from 'ts-repo-utils';
+import { environmentsDir } from '../constants.mjs';
+import { getAllEnvironments, setEnvironment } from './api/index.mjs';
+import { backupEnvironments } from './backup.mjs';
+import { type EnvironmentSettings } from './constants.mjs';
+import { readEnvironmentFiles } from './read-environment-contents.mjs';
+
+/**
+ * `repo-settings/environments/*.json` を Settings > Environments に反映する。
+ *
+ * ruleset と同じく、宣言に無い環境は消さない。 GUI で作られたものが `bk/` に
+ * 現れることが drift の見え方であって、 apply が黙って片付けてしまうと
+ * 「いつ誰が何を作ったか」を見る機会がなくなる。
+ */
+export const applyEnvironments = async (): Promise<void> => {
+  await backupEnvironments(false);
+
+  const environments = await readEnvironmentFiles();
+
+  for (const environment of environments) {
+    assertConsistent(environment);
+  }
+
+  for (const environment of environments) {
+    await setEnvironment(environment);
+  }
+
+  // 反映後の実際の値でローカルのファイルを更新する
+  {
+    const applied = await getAllEnvironments();
+
+    for (const environment of applied) {
+      const str = JSON.stringify(environment, undefined, 2);
+
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      await fs.writeFile(
+        path.resolve(environmentsDir, `${environment.name}.json`),
+        str,
+      );
+    }
+
+    // `bk/` は backup 側が makeEmptyDir から作り直す。ここで書き足すのではなく
+    // 呼び直しているのは、消えた環境のファイルが残らないようにするため。
+    // 整形もそこでまとめて走る。
+    await backupEnvironments();
+  }
+};
+
+/**
+ * GitHub 側が黙って無視する組み合わせを、送る前に落とす。
+ *
+ * `custom_branch_policies` が立っていないのに pattern が書いてあるファイルは、
+ * 読む側には「この ref だけに制限されている」と読めて、実際には何の制限にも
+ * なっていない — 一番危ない種類の嘘なので、エラーにする。
+ */
+const assertConsistent = (environment: EnvironmentSettings): void => {
+  const custom =
+    environment.deployment_branch_policy?.custom_branch_policies === true;
+
+  if (!custom && Arr.isNonEmpty(environment.deployment_branch_policies)) {
+    throw new Error(
+      [
+        `環境 "${environment.name}": deployment_branch_policies が書かれていますが、`,
+        'deployment_branch_policy.custom_branch_policies が true ではありません。',
+        'pattern は "Selected branches and tags" を選んだときにしか効きません。',
+      ].join('\n'),
+    );
+  }
+
+  // `custom` が立っている時点で TypeScript は `deployment_branch_policy` を
+  // record 側に絞り込んでいる。両方 true は JSON としては書けてしまうので、
+  // この組み合わせは送る前に落とす。
+  if (custom && environment.deployment_branch_policy.protected_branches) {
+    throw new Error(
+      `環境 "${environment.name}": protected_branches と custom_branch_policies は同時に true にできません。`,
+    );
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await applyEnvironments();
+}

package/src/github/environments/backup.mts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {
+  formatUncommittedFiles,
+  isDirectlyExecuted,
+  makeEmptyDir,
+} from 'ts-repo-utils';
+import { environmentsDir } from '../constants.mjs';
+import { getAllEnvironments } from './api/index.mjs';
+
+const backupDir = path.resolve(environmentsDir, './bk');
+
+/** Settings > Environments の現在値を `bk/` に保存する。 */
+export const backupEnvironments = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  await makeEmptyDir(backupDir);
+
+  const environments = await getAllEnvironments();
+
+  for (const environment of environments) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      path.resolve(backupDir, `${environment.name}.json`),
+      JSON.stringify(environment, undefined, 2),
+    );
+  }
+
+  if (fmt) {
+    await formatUncommittedFiles();
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await backupEnvironments();
+}

package/src/github/environments/constants.mts

@@ -0,0 +1,78 @@
+import * as t from 'ts-fortress';
+
+/**
+ * `repo-settings/environments/*.json` の型。
+ *
+ * Settings > Environments の 1 件に対応する。ファイルは「その環境の望ましい
+ * 状態」を丸ごと表しており、 GitHub 側で 2 つに分かれている次の API をまとめて
+ * 1 ファイルで管理する:
+ *
+ * - `PUT /repos/{owner}/{repo}/environments/{environment_name}`
+ * - `GET|POST|DELETE /repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies`
+ *
+ * GET が返す `protection_rules` は「有効な保護ルールだけが並ぶ配列」だが、この
+ * 型は書き込み側（ PUT の body ）に合わせた平らな形にしている。往復させる側の
+ * 形を正とするほうが、ファイルを読んで何が起きるか分かりやすいため。
+ */
+export const EnvironmentSettings = t.record({
+  name: t.string(''),
+
+  /** 「 Wait timer 」。分。 0 なら待たない。 */
+  wait_timer: t.number(0),
+
+  /** 「 Prevent self-review 」。 */
+  prevent_self_review: t.boolean(false),
+
+  /** 「 Required reviewers 」。空配列なら承認は要らない。 */
+  reviewers: t.array(
+    t.record({
+      type: t.enumType(['User', 'Team'], {
+        typeName: 'EnvironmentReviewerType',
+        defaultValue: 'User',
+      }),
+      id: t.number(0),
+    }),
+    { typeName: 'EnvironmentReviewers' },
+  ),
+
+  /**
+   * 「 Deployment branches and tags 」の選択。
+   *
+   * - `null` … 「 No restriction 」（ どの ref からでも deploy できる ）
+   * - `protected_branches: true` … 「 Protected branches only 」
+   * - `custom_branch_policies: true` … 「 Selected branches and tags 」。
+   *   具体的な pattern は下の `deployment_branch_policies` 。
+   *
+   * 2 つを同時に `true` にはできない。
+   */
+  deployment_branch_policy: t.union(
+    [
+      t.record({
+        protected_branches: t.boolean(false),
+        custom_branch_policies: t.boolean(true),
+      }),
+      t.nullType,
+    ],
+    { typeName: 'DeploymentBranchPolicySelection' },
+  ),
+
+  /**
+   * `custom_branch_policies` が `true` のときの pattern 一覧。
+   *
+   * それ以外のときは空配列でなければならない ( `applyEnvironments` が拒否する )。
+   * GitHub 側は別エンドポイントだが、「どの ref から deploy できるか」を
+   * 決めているのは選択と pattern の組で、片方だけ見ても意味を成さない。
+   */
+  deployment_branch_policies: t.array(
+    t.record({
+      name: t.string(''),
+      type: t.enumType(['branch', 'tag'], {
+        typeName: 'DeploymentBranchPolicyType',
+        defaultValue: 'branch',
+      }),
+    }),
+    { typeName: 'DeploymentBranchPolicies' },
+  ),
+});
+
+export type EnvironmentSettings = t.TypeOf<typeof EnvironmentSettings>;

package/src/github/environments/index.mts

@@ -0,0 +1,5 @@
+export * from './api/index.mjs';
+export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';
+export * from './read-environment-contents.mjs';

package/src/github/environments/read-environment-contents.mts

@@ -0,0 +1,53 @@
+import { type Dirent } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as t from 'ts-fortress';
+import { isDirectlyExecuted, Result } from 'ts-repo-utils';
+import { environmentsDir } from '../constants.mjs';
+import { EnvironmentSettings } from './constants.mjs';
+
+export const readEnvironmentFiles = async (): Promise<
+  readonly EnvironmentSettings[]
+> => readFilesIn(environmentsDir);
+
+export const readEnvironmentBackupFiles = async (): Promise<
+  readonly EnvironmentSettings[]
+> => readFilesIn(path.resolve(environmentsDir, './bk'));
+
+const readFilesIn = async (
+  dir: string,
+): Promise<readonly EnvironmentSettings[]> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const files: readonly Dirent<string>[] = await fs.readdir(dir, {
+    withFileTypes: true,
+  });
+
+  const fileContents: readonly string[] = await Promise.all(
+    files
+      .filter((d) => d.isFile())
+      .map((d) =>
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        fs.readFile(path.resolve(dir, d.name), { encoding: 'utf8' }),
+      ),
+  );
+
+  const validationResults = fileContents.map((content) =>
+    EnvironmentSettings.validate(JSON.parse(content)),
+  );
+
+  const mut_values: EnvironmentSettings[] = [];
+
+  for (const r of validationResults) {
+    if (Result.isErr(r)) {
+      throw new Error(t.validationErrorsToMessages(r.value).join('\n'));
+    }
+
+    mut_values.push(r.value);
+  }
+
+  return mut_values;
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await readEnvironmentFiles();
+}

package/src/github/index.mts

@@ -1,7 +1,9 @@
 export * from './actions-settings/index.mjs';
 export * from './constants.mjs';
+export * from './environments/index.mjs';
 export * from './pages/index.mjs';
 export * from './repository/index.mjs';
 export * from './resolve-target-repo.mjs';
 export * from './ruleset/index.mjs';
 export * from './variables/index.mjs';
+export * from './vulnerability-alerts/index.mjs';

package/src/github/vulnerability-alerts/api/get-vulnerability-alerts.mts

@@ -0,0 +1,31 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { hasKey, isRecord } from 'ts-data-forge';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { VulnerabilityAlertsSettings } from '../constants.mjs';
+
+/**
+ * Dependabot alerts が有効かどうかを取得する。
+ *
+ * このエンドポイントは body を返さない: 有効なら 204、無効なら 404。
+ * octokit は 404 を例外にするので、それを `enabled: false` として扱う。
+ * 「無効」と「読めなかった」は区別する必要があるため、 404 以外は投げ直す。
+ */
+export const getVulnerabilityAlerts =
+  async (): Promise<VulnerabilityAlertsSettings> => {
+    try {
+      // https://docs.github.com/rest/repos/repos#check-if-vulnerability-alerts-are-enabled-for-a-repository
+      await octokit.request(
+        'GET /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+        { owner: OWNER, repo: REPO, headers: octokitHeaders },
+      );
+
+      return VulnerabilityAlertsSettings.fill({ enabled: true });
+    } catch (error) {
+      if (isRecord(error) && hasKey(error, 'status') && error.status === 404) {
+        return VulnerabilityAlertsSettings.fill({ enabled: false });
+      }
+
+      throw error;
+    }
+  };

package/src/github/vulnerability-alerts/api/index.mts

@@ -0,0 +1,2 @@
+export * from './get-vulnerability-alerts.mjs';
+export * from './set-vulnerability-alerts.mjs';

package/src/github/vulnerability-alerts/api/set-vulnerability-alerts.mts

@@ -0,0 +1,31 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { type VulnerabilityAlertsSettings } from '../constants.mjs';
+
+/**
+ * Dependabot alerts を JSON の内容に合わせる。
+ *
+ * 有効化と無効化で別メソッドなので、書き込みは 1 回で済むように分岐する。
+ * `enabled: false` はきちんと無効化する — 宣言が現状に合わせて黙るなら、
+ * ファイルを読んでも何が有効なのか分からなくなる。
+ */
+export const setVulnerabilityAlerts = async (
+  settings: VulnerabilityAlertsSettings,
+): Promise<void> => {
+  if (settings.enabled) {
+    // https://docs.github.com/rest/repos/repos#enable-vulnerability-alerts
+    await octokit.request(
+      'PUT /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+      { owner: OWNER, repo: REPO, headers: octokitHeaders },
+    );
+
+    return;
+  }
+
+  // https://docs.github.com/rest/repos/repos#disable-vulnerability-alerts
+  await octokit.request(
+    'DELETE /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+    { owner: OWNER, repo: REPO, headers: octokitHeaders },
+  );
+};