alchemy 0.9.2 → 0.10.0

package/lib/github/index.d.ts

@@ -1 +1,2 @@
+export * from "./repository-environment";
 export * from "./secret";

package/lib/github/index.js

@@ -1 +1,2 @@
+export * from "./repository-environment";
 export * from "./secret";

package/lib/github/repository-environment.d.ts

@@ -0,0 +1,153 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+/**
+ * Properties for creating or updating a GitHub Repository Environment
+ */
+export interface RepositoryEnvironmentProps {
+    /**
+     * Repository owner (user or organization)
+     */
+    owner: string;
+    /**
+     * Repository name
+     */
+    repository: string;
+    /**
+     * Environment name
+     */
+    name: string;
+    /**
+     * Wait timer before allowing deployments to proceed (in minutes)
+     * Must be between 0 and 43200 (30 days)
+     * @default 0
+     */
+    waitTimer?: number;
+    /**
+     * Determine whether to prevent self-reviews on pull requests
+     * Note: Requires at least one reviewer when enabled
+     * @default false
+     */
+    preventSelfReview?: boolean;
+    /**
+     * Determine whether administrators can bypass deployment protection rules
+     * @default true
+     */
+    adminBypass?: boolean;
+    /**
+     * Required reviewers for deployments to this environment
+     */
+    reviewers?: {
+        /**
+         * GitHub usernames or user IDs that can approve deployments
+         * Can be numeric IDs or string usernames (which will be resolved to IDs)
+         */
+        users?: Array<number | string>;
+        /**
+         * GitHub team names or team IDs that can approve deployments
+         * Can be numeric IDs or string team names (which will be resolved to IDs)
+         * Note: For team names, should be in the format "org/team-name"
+         */
+        teams?: Array<number | string>;
+    };
+    /**
+     * Deployment branch policy for the environment
+     */
+    deploymentBranchPolicy?: {
+        /**
+         * Whether to restrict deployments to protected branches
+         * @default false
+         */
+        protectedBranches?: boolean;
+        /**
+         * Whether to allow custom branch policies
+         * When true, specific branch patterns can be specified using createDeploymentBranchPolicy
+         * @default false
+         */
+        customBranchPolicies?: boolean;
+    };
+    /**
+     * Branch patterns for deployment when customBranchPolicies is true
+     * For example: ["main", "releases/*"]
+     * @default []
+     */
+    branchPatterns?: string[];
+    /**
+     * Optional GitHub API token (overrides environment variable)
+     * If not provided, will use GITHUB_TOKEN environment variable
+     * @default process.env.GITHUB_TOKEN
+     */
+    token?: string;
+}
+/**
+ * Output returned after Repository Environment creation/update
+ */
+export interface RepositoryEnvironment extends Resource<"github::RepositoryEnvironment">, RepositoryEnvironmentProps {
+    /**
+     * The ID of the resource
+     */
+    id: string;
+    /**
+     * The numeric ID of the environment in GitHub
+     */
+    environmentId: number;
+    /**
+     * Time at which the object was created/updated
+     */
+    updatedAt: string;
+}
+/**
+ * Resource for managing GitHub repository environments
+ *
+ * Note: If preventSelfReview is true, at least one reviewer must be specified.
+ *
+ * Branch policies are efficiently managed with proper diffing:
+ * - Only manages branch patterns configured through this resource
+ * - Preserves any manually added branch patterns outside this resource
+ * - When updating, only modifies patterns that have changed from previous state
+ * - Compares against previous resource state, not current environment state
+ * - Safely handles policy type changes
+ *
+ * @example
+ * // Create a basic environment with no protection rules
+ * const devEnv = await RepositoryEnvironment("dev-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "development"
+ * });
+ *
+ * @example
+ * // Create a production environment with approval requirements
+ * const prodEnv = await RepositoryEnvironment("prod-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "production",
+ *   waitTimer: 10, // 10 minute delay
+ *   preventSelfReview: true,
+ *   reviewers: {
+ *     teams: ["platform-team"], // team name
+ *     users: ["security-admin"] // username
+ *   },
+ *   deploymentBranchPolicy: {
+ *     protectedBranches: true,
+ *     customBranchPolicies: false
+ *   }
+ * });
+ *
+ * @example
+ * // Create an environment with reviewer IDs
+ * const stagingEnv = await RepositoryEnvironment("staging-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "staging",
+ *   reviewers: {
+ *     teams: [1234567], // team ID
+ *     users: [7654321]  // user ID
+ *   },
+ *   deploymentBranchPolicy: {
+ *     protectedBranches: false,
+ *     customBranchPolicies: true
+ *   },
+ *   branchPatterns: ["main", "release/*"]
+ * });
+ */
+export declare const RepositoryEnvironment: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<RepositoryEnvironment>, id: string, props: RepositoryEnvironmentProps) => Promise<RepositoryEnvironment>);

package/lib/github/repository-environment.js

@@ -0,0 +1,295 @@
+import { Resource } from "../resource";
+import { createGitHubClient, verifyGitHubAuth } from "./client";
+/**
+ * Resource for managing GitHub repository environments
+ *
+ * Note: If preventSelfReview is true, at least one reviewer must be specified.
+ *
+ * Branch policies are efficiently managed with proper diffing:
+ * - Only manages branch patterns configured through this resource
+ * - Preserves any manually added branch patterns outside this resource
+ * - When updating, only modifies patterns that have changed from previous state
+ * - Compares against previous resource state, not current environment state
+ * - Safely handles policy type changes
+ *
+ * @example
+ * // Create a basic environment with no protection rules
+ * const devEnv = await RepositoryEnvironment("dev-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "development"
+ * });
+ *
+ * @example
+ * // Create a production environment with approval requirements
+ * const prodEnv = await RepositoryEnvironment("prod-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "production",
+ *   waitTimer: 10, // 10 minute delay
+ *   preventSelfReview: true,
+ *   reviewers: {
+ *     teams: ["platform-team"], // team name
+ *     users: ["security-admin"] // username
+ *   },
+ *   deploymentBranchPolicy: {
+ *     protectedBranches: true,
+ *     customBranchPolicies: false
+ *   }
+ * });
+ *
+ * @example
+ * // Create an environment with reviewer IDs
+ * const stagingEnv = await RepositoryEnvironment("staging-environment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "staging",
+ *   reviewers: {
+ *     teams: [1234567], // team ID
+ *     users: [7654321]  // user ID
+ *   },
+ *   deploymentBranchPolicy: {
+ *     protectedBranches: false,
+ *     customBranchPolicies: true
+ *   },
+ *   branchPatterns: ["main", "release/*"]
+ * });
+ */
+export const RepositoryEnvironment = Resource("github::RepositoryEnvironment", async function (id, props) {
+    // Create authenticated Octokit client
+    const octokit = await createGitHubClient({
+        token: props.token,
+    });
+    // Verify authentication and permissions
+    if (!this.quiet) {
+        await verifyGitHubAuth(octokit, props.owner, props.repository);
+    }
+    if (this.phase === "delete") {
+        if (this.output?.id) {
+            try {
+                // Delete the environment
+                await octokit.rest.repos.deleteAnEnvironment({
+                    owner: props.owner,
+                    repo: props.repository,
+                    environment_name: props.name,
+                });
+            }
+            catch (error) {
+                // Ignore 404 errors (environment already deleted)
+                if (error.status === 404) {
+                    console.log("Environment doesn't exist, ignoring");
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        // Return void (a deleted resource has no content)
+        return this.destroy();
+    }
+    else {
+        try {
+            // Check if the environment already exists
+            let environmentId = undefined; // Use undefined instead of 0
+            try {
+                const { data: environments } = await octokit.rest.repos.getAllEnvironments({
+                    owner: props.owner,
+                    repo: props.repository,
+                });
+                const existingEnv = environments.environments?.find((env) => env.name.toLowerCase() === props.name.toLowerCase());
+                if (existingEnv?.id) {
+                    environmentId = existingEnv.id;
+                }
+            }
+            catch (error) {
+                // If it's a 404, the environment doesn't exist, which is fine
+                if (error.status !== 404) {
+                    throw error;
+                }
+            }
+            // Convert reviewers to API format
+            const reviewers = [];
+            // Process user reviewers
+            if (props.reviewers?.users && props.reviewers.users.length > 0) {
+                for (const user of props.reviewers.users) {
+                    if (typeof user === "number") {
+                        // If a numeric ID is provided, use it directly
+                        reviewers.push({
+                            type: "User",
+                            id: user,
+                        });
+                    }
+                    else {
+                        // If a username string is provided, look up the ID
+                        const { data: userData } = await octokit.rest.users.getByUsername({
+                            username: user,
+                        });
+                        reviewers.push({
+                            type: "User",
+                            id: userData.id,
+                        });
+                    }
+                }
+            }
+            // Process team reviewers
+            if (props.reviewers?.teams && props.reviewers.teams.length > 0) {
+                for (const team of props.reviewers.teams) {
+                    if (typeof team === "number") {
+                        // If a numeric ID is provided, use it directly
+                        reviewers.push({
+                            type: "Team",
+                            id: team,
+                        });
+                    }
+                    else {
+                        // If a team name string is provided, look up the ID
+                        // Check if team name is in the format 'org/team-name'
+                        const teamParts = team.includes("/")
+                            ? team.split("/")
+                            : [props.owner, team];
+                        if (teamParts.length !== 2) {
+                            throw new Error(`Invalid team format: ${team}. Expected format: "org/team-slug" or just "team-slug"`);
+                        }
+                        const [org, teamSlug] = teamParts;
+                        const { data: teamData } = await octokit.rest.teams.getByName({
+                            org,
+                            team_slug: teamSlug,
+                        });
+                        reviewers.push({
+                            type: "Team",
+                            id: teamData.id,
+                        });
+                    }
+                }
+            }
+            // Create or update the environment
+            if (environmentId === undefined) {
+                // Create the environment
+                const { data: createdEnv } = await octokit.rest.repos.createOrUpdateEnvironment({
+                    owner: props.owner,
+                    repo: props.repository,
+                    environment_name: props.name,
+                    wait_timer: props.waitTimer,
+                    prevent_self_review: props.preventSelfReview,
+                    reviewers: reviewers.length > 0 ? reviewers : undefined,
+                    deployment_branch_policy: props.deploymentBranchPolicy
+                        ? {
+                            protected_branches: props.deploymentBranchPolicy.protectedBranches ?? false,
+                            custom_branch_policies: props.deploymentBranchPolicy.customBranchPolicies ??
+                                false,
+                        }
+                        : undefined,
+                });
+                environmentId = createdEnv.id;
+                // If there are specific branch patterns, set them
+                if (props.deploymentBranchPolicy?.customBranchPolicies === true &&
+                    props.branchPatterns &&
+                    props.branchPatterns.length > 0) {
+                    // Add branch patterns one by one
+                    for (const pattern of props.branchPatterns) {
+                        await octokit.rest.repos.createDeploymentBranchPolicy({
+                            owner: props.owner,
+                            repo: props.repository,
+                            environment_name: props.name,
+                            name: pattern,
+                        });
+                    }
+                }
+            }
+            else {
+                // Update the environment
+                await octokit.rest.repos.createOrUpdateEnvironment({
+                    owner: props.owner,
+                    repo: props.repository,
+                    environment_name: props.name,
+                    wait_timer: props.waitTimer,
+                    prevent_self_review: props.preventSelfReview,
+                    reviewers: reviewers.length > 0 ? reviewers : undefined,
+                    deployment_branch_policy: props.deploymentBranchPolicy
+                        ? {
+                            protected_branches: props.deploymentBranchPolicy.protectedBranches ?? false,
+                            custom_branch_policies: props.deploymentBranchPolicy.customBranchPolicies ?? false,
+                        }
+                        : undefined,
+                });
+                // If there are specific branch patterns, update them
+                if (props.deploymentBranchPolicy?.customBranchPolicies === true) {
+                    // Get existing branch policies to understand what's currently configured
+                    const { data: existingPolicies } = await octokit.rest.repos.listDeploymentBranchPolicies({
+                        owner: props.owner,
+                        repo: props.repository,
+                        environment_name: props.name,
+                    });
+                    const existingPatterns = existingPolicies.branch_policies.map((policy) => policy.name);
+                    const newPatterns = props.branchPatterns || [];
+                    // For updates, keep track of which branch policies we should manage
+                    // This set identifies patterns that were previously managed by this resource
+                    // If we don't have previous props, use an empty set
+                    const previouslyManagedPatterns = new Set(this.phase === "update" &&
+                        this.props?.deploymentBranchPolicy?.customBranchPolicies === true
+                        ? this.props.branchPatterns || []
+                        : []);
+                    // Patterns to add (in new config but not in existing)
+                    const patternsToAdd = newPatterns.filter((pattern) => !existingPatterns.includes(pattern));
+                    // Patterns to delete (were managed by us previously but not in new config)
+                    const patternsToDelete = existingPatterns.filter((pattern) => previouslyManagedPatterns.has(pattern) &&
+                        !newPatterns.includes(pattern));
+                    // Delete policies that are no longer needed
+                    for (const patternToDelete of patternsToDelete) {
+                        const policy = existingPolicies.branch_policies.find((p) => p.name === patternToDelete);
+                        if (policy?.id) {
+                            await octokit.rest.repos.deleteDeploymentBranchPolicy({
+                                owner: props.owner,
+                                repo: props.repository,
+                                environment_name: props.name,
+                                branch_policy_id: policy.id,
+                            });
+                        }
+                    }
+                    // Add new branch patterns
+                    for (const pattern of patternsToAdd) {
+                        await octokit.rest.repos.createDeploymentBranchPolicy({
+                            owner: props.owner,
+                            repo: props.repository,
+                            environment_name: props.name,
+                            name: pattern,
+                        });
+                    }
+                }
+            }
+            // Get the updated environment details
+            const { data: env } = await octokit.rest.repos.getEnvironment({
+                owner: props.owner,
+                repo: props.repository,
+                environment_name: props.name,
+            });
+            // Return environment details
+            return this({
+                id: `${props.owner}/${props.repository}/${props.name}`,
+                environmentId: environmentId || env.id,
+                owner: props.owner,
+                repository: props.repository,
+                name: props.name,
+                waitTimer: props.waitTimer,
+                preventSelfReview: props.preventSelfReview,
+                adminBypass: props.adminBypass,
+                reviewers: props.reviewers,
+                deploymentBranchPolicy: props.deploymentBranchPolicy,
+                branchPatterns: props.branchPatterns,
+                token: props.token,
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            if (error.status === 403 &&
+                error.message?.includes("Must have admin rights")) {
+                console.error("\n⚠️ Error creating/updating GitHub environment: You must have admin rights to the repository.");
+                console.error("Make sure your GitHub token has the required permissions (repo scope for private repos).\n");
+            }
+            else {
+                console.error("Error creating/updating GitHub environment:", error.message);
+            }
+            throw error;
+        }
+    }
+});

package/lib/github/secret.d.ts

@@ -21,6 +21,11 @@ export interface GitHubSecretProps {
      * Secret value (will be stored securely on GitHub)
      */
     value: Secret;
+    /**
+     * Optional environment name to create an environment secret
+     * If set, the secret will be created in the specified environment instead of at the repository level
+     */
+    environment?: string;
     /**
      * Optional GitHub API token (overrides environment variable)
      * If not provided, will use GITHUB_TOKEN environment variable
@@ -43,7 +48,7 @@ export interface GitHubSecretOutput extends Resource<"github::Secret">, Omit<Git
     updatedAt: string;
 }
 /**
- * Resource for managing GitHub repository secrets
+ * Resource for managing GitHub repository and environment secrets
  *
  * Authentication is handled in the following order:
  * 1. `token` parameter in the resource props (if provided)
@@ -54,7 +59,7 @@ export interface GitHubSecretOutput extends Resource<"github::Secret">, Omit<Git
  * - 'public_repo' scope for public repositories
  *
  * @example
- * // Create a secret using GITHUB_TOKEN environment variable:
+ * // Create a repository secret using GITHUB_TOKEN environment variable:
  * const secret = await GitHubSecret("my-secret", {
  *   owner: "my-github-username",
  *   repository: "my-repo",
@@ -63,6 +68,16 @@ export interface GitHubSecretOutput extends Resource<"github::Secret">, Omit<Git
  * });
  *
  * @example
+ * // Create an environment secret:
+ * const secret = await GitHubSecret("my-env-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   environmentName: "production",
+ *   name: "DEPLOY_KEY",
+ *   value: alchemy.secret("my-secret-deploy-key")
+ * });
+ *
+ * @example
  * // Create a secret with a custom GitHub token:
  * const secret = await GitHubSecret("my-secret", {
  *   owner: "my-github-username",

package/lib/github/secret.js

@@ -2,7 +2,7 @@ import sodium from "libsodium-wrappers";
 import { Resource } from "../resource";
 import { createGitHubClient, verifyGitHubAuth } from "./client";
 /**
- * Resource for managing GitHub repository secrets
+ * Resource for managing GitHub repository and environment secrets
  *
  * Authentication is handled in the following order:
  * 1. `token` parameter in the resource props (if provided)
@@ -13,7 +13,7 @@ import { createGitHubClient, verifyGitHubAuth } from "./client";
  * - 'public_repo' scope for public repositories
  *
  * @example
- * // Create a secret using GITHUB_TOKEN environment variable:
+ * // Create a repository secret using GITHUB_TOKEN environment variable:
  * const secret = await GitHubSecret("my-secret", {
  *   owner: "my-github-username",
  *   repository: "my-repo",
@@ -22,6 +22,16 @@ import { createGitHubClient, verifyGitHubAuth } from "./client";
  * });
  *
  * @example
+ * // Create an environment secret:
+ * const secret = await GitHubSecret("my-env-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   environmentName: "production",
+ *   name: "DEPLOY_KEY",
+ *   value: alchemy.secret("my-secret-deploy-key")
+ * });
+ *
+ * @example
  * // Create a secret with a custom GitHub token:
  * const secret = await GitHubSecret("my-secret", {
  *   owner: "my-github-username",
@@ -72,15 +82,27 @@ export const GitHubSecret = Resource("github::Secret", async function (id, props
     if (!this.quiet) {
         await verifyGitHubAuth(octokit, props.owner, props.repository);
     }
+    // Determine if we're working with an environment secret or repository secret
+    const isEnvironmentSecret = !!props.environment;
     if (this.phase === "delete") {
         if (this.output?.id) {
             try {
                 // Delete the secret
-                await octokit.rest.actions.deleteRepoSecret({
-                    owner: props.owner,
-                    repo: props.repository,
-                    secret_name: props.name,
-                });
+                if (isEnvironmentSecret) {
+                    await octokit.rest.actions.deleteEnvironmentSecret({
+                        owner: props.owner,
+                        repo: props.repository,
+                        environment_name: props.environment,
+                        secret_name: props.name,
+                    });
+                }
+                else {
+                    await octokit.rest.actions.deleteRepoSecret({
+                        owner: props.owner,
+                        repo: props.repository,
+                        secret_name: props.name,
+                    });
+                }
             }
             catch (error) {
                 // Ignore 404 errors (secret already deleted)
@@ -97,27 +119,96 @@ export const GitHubSecret = Resource("github::Secret", async function (id, props
     }
     else {
         try {
-            // Get the repository's public key for encrypting secrets
-            const { data: publicKey } = await octokit.rest.actions.getRepoPublicKey({
-                owner: props.owner,
-                repo: props.repository,
-            });
+            // Check if we're transitioning between secret types (repo <-> environment)
+            if (this.phase === "update") {
+                const wasEnvironmentSecret = !!this.output.environment;
+                const secretTypeChanged = isEnvironmentSecret !== wasEnvironmentSecret;
+                // If secret type changed, we need to delete the old one first
+                if (secretTypeChanged) {
+                    console.log(`Secret type changed from ${wasEnvironmentSecret ? "environment" : "repository"} to ${isEnvironmentSecret ? "environment" : "repository"} secret. Deleting the old secret first.`);
+                    try {
+                        if (wasEnvironmentSecret) {
+                            // Delete the old environment secret
+                            await octokit.rest.actions.deleteEnvironmentSecret({
+                                owner: this.output.owner,
+                                repo: this.output.repository,
+                                environment_name: this.output.environment,
+                                secret_name: this.output.name,
+                            });
+                        }
+                        else {
+                            // Delete the old repository secret
+                            await octokit.rest.actions.deleteRepoSecret({
+                                owner: this.output.owner,
+                                repo: this.output.repository,
+                                secret_name: this.output.name,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // Log but don't fail if the old secret doesn't exist or can't be deleted
+                        if (error.status === 404) {
+                            console.log("Old secret not found, continuing with creation of new secret");
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+            }
+            let publicKey;
+            // Get the appropriate public key for encrypting secrets
+            if (isEnvironmentSecret) {
+                // Get the environment's public key
+                const { data } = await octokit.rest.actions.getEnvironmentPublicKey({
+                    owner: props.owner,
+                    repo: props.repository,
+                    environment_name: props.environment,
+                });
+                publicKey = data;
+            }
+            else {
+                // Get the repository's public key
+                const { data } = await octokit.rest.actions.getRepoPublicKey({
+                    owner: props.owner,
+                    repo: props.repository,
+                });
+                publicKey = data;
+            }
             // Encrypt the secret value using libsodium
             const encryptedValue = await encryptString(props.value.unencrypted, publicKey.key);
             // Create or update the secret with the encrypted value and key_id
-            await octokit.rest.actions.createOrUpdateRepoSecret({
-                owner: props.owner,
-                repo: props.repository,
-                secret_name: props.name,
-                encrypted_value: encryptedValue,
-                key_id: publicKey.key_id,
-            });
+            if (isEnvironmentSecret) {
+                await octokit.rest.actions.createOrUpdateEnvironmentSecret({
+                    owner: props.owner,
+                    repo: props.repository,
+                    environment_name: props.environment,
+                    secret_name: props.name,
+                    encrypted_value: encryptedValue,
+                    key_id: publicKey.key_id,
+                });
+            }
+            else {
+                await octokit.rest.actions.createOrUpdateRepoSecret({
+                    owner: props.owner,
+                    repo: props.repository,
+                    secret_name: props.name,
+                    encrypted_value: encryptedValue,
+                    key_id: publicKey.key_id,
+                });
+            }
             // GitHub doesn't return the secret details on create/update, so we need to construct it
+            const idParts = [props.owner, props.repository];
+            if (isEnvironmentSecret) {
+                idParts.push(props.environment);
+            }
+            idParts.push(props.name);
             return this({
-                id: `${props.owner}/${props.repository}/${props.name}`,
+                id: idParts.join("/"),
                 owner: props.owner,
                 repository: props.repository,
                 name: props.name,
+                environment: props.environment,
                 token: props.token,
                 updatedAt: new Date().toISOString(),
             });