Release Security Controls

This document describes the security controls that protect the Aranya release pipeline. These controls also enforce our QA process: peer review ensures test coverage, CI runs automated tests on every PR and release, and required status checks and approvals must pass before merging. For the release process itself, see Release Process.

Implementation Checklist

All items below are tracked under aranya#730.

Branch Protections

Default branch protection rules are configured at the org level (aranya-project org rulesets) and apply to all repos. Repo-level overrides or additional rules can be configured per repo under Settings > Rules > Rulesets.

The following branches must be protected:

• main – used for normal product releases (major and minor versions). Protected by org-level default rules.
• release/**/* – used for patch releases and any other releases not performed from main. Protected by an org-level wildcard branch protection rule.

Required branch protection settings. These are configured at the org level unless noted as repo-specific:

Branch protections should only be bypassed by team members with elevated permissions under special documented circumstances (e.g. by team leads or admin with a documented paper trail explaining the rationale).

Code Review

• CODEOWNERS (aranya) have been defined based on corresponding team leads and subject matter experts. Those who have reviewed sections of code or worked on that code before may additionally be considered a code owner. (repo-level: .github/CODEOWNERS file in each repo)
• Before merging PRs, review is required from at least one code owner and at least one other internal engineer. External contributor reviews do not count toward required approvals. (enforced by branch protection settings above)
• Security-critical changes and release PRs require approval from at least 2 team leads, code owners, or key stakeholders.
• All code must be human-reviewed before others are expected to review a PR, including any AI-generated code.

CI/CD

CI/CD runs on main and all PRs/feature branches. Workflow files are repo-level (committed in each repo’s .github/workflows/ directory). Required status checks are also repo-level since each repo has different workflows and jobs.

The release-critical workflows are release.yml and publish.yml (aranya) and release-plz.yml (aranya-core). These handle tagging, publishing crates to crates.io, and uploading release artifacts.

Additional CI/CD policies:

• CI/CD includes security vulnerability scans, cargo vet, linting, unit tests, integration tests, formatting, etc.
• Release workflows create tags, publish crates to crates.io, and upload release artifacts. They trigger on pushes to main and release/**/* branches: release.yml and publish.yml (aranya) and release-plz.yml (aranya-core).
• CI/CD runners are only available to users within our GitHub organization, with proper repo permissions assigned to them. External users require manual approval to run CI/CD jobs on our runners. (org-level: Actions settings > Fork pull request workflows > Require approval for all outside collaborators) This prevents unwanted accumulation of cost on ephemeral cloud runners and potential exploitation of self-hosted runners.
• All branch protection checks must pass before merging.

Release Environment Protections

Release workflows (release.yml and publish.yml in aranya, release-plz.yml in aranya-core) use a GitHub Environment to gate access to release secrets and provide an additional approval step. Environment settings (repo-level): aranya, aranya-core.

Required reviewers is a built-in GitHub feature for environment protections. When a workflow job references an environment with required reviewers, GitHub pauses the workflow and notifies the designated reviewers. The workflow cannot proceed until a reviewer approves the deployment in the GitHub Actions UI. No third-party actions are needed.

Limitation: Environment approvals only require a single approval from anyone on the reviewer list — there is no way to require multiple approvals or to require a specific person plus additional approvers. For multi-reviewer requirements on the release PR (e.g., 1 lead + 2 other reviewers), use branch protection rules on release/**/* branches instead. The environment gate serves as a final confirmation from a team lead after the PR has already been reviewed and merged.

The release environment is configured in both aranya and aranya-core. The release workflow jobs in both repos reference it:

# aranya release.yml (https://github.com/aranya-project/aranya/blob/main/.github/workflows/release.yml)
jobs:
  tag:
    environment: release
    ...

# aranya-core release-plz.yml (https://github.com/aranya-project/aranya-core/blob/main/.github/workflows/release-plz.yml)
jobs:
  release-plz-release:
    environment: release
    ...

This prevents an attacker from modifying a workflow on an unprotected branch to trigger an unauthorized release, since the environment will block execution and deny access to secrets.

Secrets Management

Release credentials are scoped to the release environment rather than stored as repo-level secrets, so unprotected branches cannot access them. GitHub does not support org-level environments (community request), so environment-scoped secrets must be duplicated in each repo’s release environment that needs them.

ARANYA_BOT_CRATESIO_CARGO_LOGIN_KEY is stored in the release environment in both repos (aranya, aranya-core). The workflows reference this secret as secrets.ARANYA_BOT_CRATESIO_CARGO_LOGIN_KEY. Because org-level environments are not available, the secret is configured separately in each repo’s release environment.

• The crates.io API key is rotated after each release to limit the window of exposure if a key is compromised (see Post-Release Checklist).