GitHub.Actions reference

Environment

Source: src/GitHub/Environment.ts

A GitHub Actions deployment environment.

Environment manages a repository’s deployment environment (e.g. production, staging) along with its protection rules: required reviewers, wait timers, self-review prevention, and deployment branch policies. Pair it with GitHub.Secret and GitHub.Variable (both accept an environment prop) to scope configuration to the environment.

Environments are available on public repositories on every plan; private repositories require GitHub Pro, Team, or Enterprise, and protection rules on private repositories require Team or Enterprise.

Authentication is resolved via the GitHubCredentials service supplied by GitHub.providers() (env, stored PAT, gh CLI, or OAuth). The token needs repo scope.

Environment: Creating an Environment

Basic Environment

const production = yield* GitHub.Environment("production", {
  owner: "my-org",
  repository: "my-repo",
  name: "production",
});

Environment with Protection Rules

yield* GitHub.Environment("production", {
  owner: "my-org",
  repository: "my-repo",
  name: "production",
  waitTimer: 30,
  preventSelfReview: true,
  reviewers: {
    users: ["release-manager"],
    teams: ["platform"],
  },
});

Environment: Deployment Branch Policies

Restrict to Protected Branches

yield* GitHub.Environment("production", {
  owner: "my-org",
  repository: "my-repo",
  name: "production",
  deploymentBranchPolicy: { protectedBranches: true },
});

Restrict to Branch Name Patterns

yield* GitHub.Environment("production", {
  owner: "my-org",
  repository: "my-repo",
  name: "production",
  deploymentBranchPolicy: {
    customBranchPolicies: ["main", "release/*"],
  },
});

Environment: Environment Secrets and Variables

const env = yield* GitHub.Environment("production", {
  owner: "my-org",
  repository: "my-repo",
  name: "production",
});

yield* GitHub.Secret("deploy-key", {
  owner: "my-org",
  repository: "my-repo",
  environment: env,
  name: "DEPLOY_KEY",
  value: Redacted.make("my-secret-value"),
});

yield* GitHub.Variable("region", {
  owner: "my-org",
  repository: "my-repo",
  environment: env,
  name: "AWS_REGION",
  value: "us-east-1",
});

Secret

Source: src/GitHub/Secret.ts

A GitHub Actions repository or environment secret.

Secret manages the lifecycle of an encrypted secret in GitHub Actions. Secrets are encrypted using the repository’s (or environment’s) public key via libsodium before being stored. The resource is idempotent — calling it with the same name will update the secret value in place.

Authentication is resolved via the GitHubCredentials service supplied by GitHub.providers() (which uses the Alchemy AuthProvider — env, stored PAT, gh CLI, or OAuth). The token needs repo scope for private repositories or public_repo for public ones.

Secret: Repository Secrets

Store secrets accessible to all GitHub Actions workflows in the repository.

yield* GitHub.Secret("aws-role", {
  owner: "my-org",
  repository: "my-repo",
  name: "AWS_ROLE_ARN",
  value: Redacted.make(role.roleArn),
});

Secret: Environment Secrets

Scope a secret to a specific GitHub Actions environment (e.g. production, staging). Environment secrets require environment protection rules to be satisfied before workflows can access them.

yield* GitHub.Secret("deploy-key", {
  owner: "my-org",
  repository: "my-repo",
  environment: "production",
  name: "DEPLOY_KEY",
  value: Redacted.make("my-secret-value"),
});

Secret: Wiring with Other Resources

A common pattern is wiring the output of another resource — like an IAM role ARN or a database URL — directly into a GitHub secret so that CI workflows can use it.

Store an IAM Role ARN for CI

const role = yield* AWS.IAM.Role("ci-role", { ... });

yield* GitHub.Secret("ci-role-arn", {
  owner: "my-org",
  repository: "my-repo",
  name: "AWS_ROLE_ARN",
  value: Redacted.make(role.roleArn),
});

Store Multiple Secrets

yield* GitHub.Secret("db-url", {
  owner: "my-org",
  repository: "my-repo",
  environment: "production",
  name: "DATABASE_URL",
  value: Redacted.make(database.connectionString),
});

yield* GitHub.Secret("api-key", {
  owner: "my-org",
  repository: "my-repo",
  environment: "production",
  name: "API_KEY",
  value: Redacted.make(apiKey),
});

Secrets

Source: src/GitHub/Secrets.ts

Bulk-creates a set of Secrets in the same repository (and optionally the same environment).

Each entry in secrets becomes one GitHub.Secret resource, using the map key as both the alchemy logical id and the secret name.

Secrets: Examples

yield* GitHub.Secrets({
  owner: "my-org",
  repository: "my-repo",
  secrets: {
    AXIOM_INGEST_TOKEN: tokenValue,
    AXIOM_DATASET_TRACES: traces.name,
  },
});

Variable

Source: src/GitHub/Variable.ts

A GitHub Actions repository variable.

Variable manages the lifecycle of a plain-text configuration variable in GitHub Actions. Variables are visible in workflow logs and are suitable for non-sensitive configuration like region names, environment labels, or feature flags. For sensitive values, use GitHub.Secret instead.

Variable: Repository Variables

Store variables accessible to all GitHub Actions workflows in the repository.

yield* GitHub.Variable("aws-region", {
  owner: "my-org",
  repository: "my-repo",
  name: "AWS_REGION",
  value: "us-east-1",
});

Variable: Environment Variables

Scope a variable to a specific GitHub Actions environment (e.g. production, staging). Use GitHub.Environment to manage the environment itself.

yield* GitHub.Variable("region", {
  owner: "my-org",
  repository: "my-repo",
  environment: "production",
  name: "AWS_REGION",
  value: "us-east-1",
});

Variable: Wiring with Other Resources

Pass output attributes from other resources into GitHub variables so that CI workflows can reference them.

Store a Worker URL for CI

const worker = yield* Cloudflare.Worker("Api", { ... });

yield* GitHub.Variable("api-url", {
  owner: "my-org",
  repository: "my-repo",
  name: "API_URL",
  value: worker.url!,
});

Multiple Variables

yield* GitHub.Variable("region", {
  owner: "my-org",
  repository: "my-repo",
  name: "AWS_REGION",
  value: "us-east-1",
});

yield* GitHub.Variable("stage", {
  owner: "my-org",
  repository: "my-repo",
  name: "DEPLOY_STAGE",
  value: "production",
});

Variables

Source: src/GitHub/Variables.ts

Bulk-creates a set of Variables in the same repository.

Plural counterpart of Secrets, for non-sensitive values like region names, role ARNs, environment labels, or feature flags.

Variables: Examples

yield* GitHub.Variables({
  owner: "my-org",
  repository: "my-repo",
  variables: {
    AWS_ROLE_ARN: role.roleArn,
    AWS_REGION: region,
  },
});