Skip to content

GitHub Environments Setup

uptool uses GitHub Environments with approval gates to control releases. This provides an additional layer of security and creates an audit trail for all releases.

Overview

Three environments are configured in the release workflows:

  1. pre-release - Used for creating pre-release versions (rc/beta/alpha)
  2. production - Used for promoting pre-releases to stable versions
  3. patch-release - Used for creating patch releases on release branches

All environments require manual approval from designated reviewers before the workflow can proceed with creating/promoting releases.

Environment Configuration

Prerequisites

  • Repository administrator access
  • Appropriate repository permissions (Settings → Environments)

Creating Environments

1. Navigate to Environments

  1. Go to your repository on GitHub
  2. Click Settings (top menu)
  3. In the left sidebar, click Environments

2. Create Pre-Release Environment

  1. Click New environment
  2. Name: pre-release
  3. Click Configure environment

Configure the following protection rules:

  • ✅ Required reviewers
  • Add maintainers who should approve pre-releases
  • Recommended: At least 1 reviewer

  • Prevents accidental pre-release creation

  • ✅ Wait timer (optional)

  • Set to 0 minutes (no automatic delay)

  • Or add a delay if desired

  • ✅ Deployment branches and tags

  • Select: Selected branches and tags
  • Add rule: main branch only
  • This ensures only main branch can create releases

Environment secrets (if needed):

  • No additional secrets required for basic setup
  • GitHub token is automatically provided

Save the environment

3. Create Production Environment

  1. Click New environment
  2. Name: production
  3. Click Configure environment

Configure the following protection rules:

  • ✅ Required reviewers
  • Add maintainers who should approve stable releases
  • Recommended: At least 2 reviewers for production

  • Requires multiple approvals for critical releases

  • ✅ Wait timer (optional)

  • Set to 0 minutes for immediate review

  • Or set to 10-30 minutes for time to review changes

  • ✅ Deployment branches and tags

  • Select: Selected branches and tags
  • Add rule: main branch only

  • Ensures only main branch can promote to stable

  • ⚠️ Prevent self-review (recommended)

  • Enable this to require approval from someone other than the workflow trigger

Environment secrets (if needed):

  • No additional secrets required for basic setup

Save the environment

4. Create Patch Release Environment

  1. Click New environment
  2. Name: patch-release
  3. Click Configure environment

Configure the following protection rules:

  • ✅ Required reviewers
  • Add maintainers who should approve patch releases
  • Recommended: At least 1 reviewer (can be same as pre-release)

  • Ensures security/bug fixes are reviewed before release

  • ✅ Wait timer (optional)

  • Set to 0 minutes for immediate review

  • Patch releases are typically urgent (security fixes)

  • ✅ Deployment branches and tags

  • Select: Selected branches and tags
  • Add pattern: release-* (for release branches)

  • This ensures only release branches can create patch releases

  • ⚠️ Prevent self-review (recommended)

  • Enable this for security patches especially

Environment secrets (if needed):

  • No additional secrets required for basic setup

Save the environment

Approval Workflow

Pre-Release Creation

When someone triggers the Pre-Release workflow:

  1. Workflow calculates version and updates files
  2. Tests run automatically
  3. Workflow pauses at the build job
  4. GitHub sends notification to required reviewers
  5. Reviewer(s) must approve or reject the deployment
  6. If approved: artifacts are built and pre-release is created
  7. If rejected: workflow is cancelled

Approval screen shows:

  • Pre-release version (e.g., v0.2.0-rc1)
  • Commit SHA being released
  • Link to the release page (once approved)
  • Comment field for approval notes

Stable Release Promotion

When someone triggers the Promote to Stable Release workflow:

  1. Workflow validates pre-release tag exists
  2. Updates version files to stable
  3. Tests run automatically
  4. Workflow pauses at the promote job
  5. GitHub sends notification to required reviewers
  6. Reviewer(s) must approve or reject the deployment
  7. If approved: artifacts are promoted and stable release is created
  8. If rejected: workflow is cancelled

Approval screen shows:

  • Pre-release being promoted (e.g., v0.2.0-rc1)
  • Stable version (e.g., v0.2.0)
  • Link to the stable release page (once approved)

Patch Release Creation

When someone triggers the Patch Release workflow:

  1. Workflow validates release branch exists
  2. Updates version files on release branch
  3. Builds binaries and generates SBOMs
  4. Workflow pauses at the release job
  5. GitHub sends notification to required reviewers
  6. Reviewer(s) must approve or reject the deployment
  7. If approved: artifacts are signed and patch release is created
  8. If rejected: workflow is cancelled

Approval screen shows:

  • Release branch (e.g., release-0.1)
  • Patch version (e.g., v0.1.1)
  • Patch type (security or bugfix)
  • Commits included in patch
  • Link to the patch release page (once approved)

Approving a Deployment

As a Reviewer

When you receive a deployment approval request:

  1. Check your email or GitHub notifications
  2. Go to Actions tab in the repository
  3. Find the workflow run waiting for approval
  4. Review the details:
  5. Check the version being released
  6. Review the commits included
  7. Verify tests passed

  8. Check CHANGELOG updates

  9. Click Review deployments

  10. Select the environment (pre-release, production, or patch-release)
  11. Add a comment (optional but recommended):
Approved: Version v0.2.0 includes security fixes
  1. Click Approve and deploy or Reject

Review Checklist

Before approving a pre-release:

  • Version number is correct
  • All tests passed
  • No breaking changes without documentation
  • CHANGELOG is updated
  • Commit messages follow conventional commits

Before approving a stable release:

  • Pre-release was tested successfully
  • No critical issues reported
  • Documentation is accurate
  • Version matches what was tested
  • All artifacts are present

Before approving a patch release:

  • Patch is on correct release branch (e.g., release-0.1)
  • Version increment is correct (patch only)
  • Security vulnerability is properly fixed (if security patch)
  • Changes are minimal and targeted (no feature additions)
  • All tests passed on release branch
  • No conflicts with existing stable releases

Viewing Deployment History

GitHub tracks all deployments in the environment:

  1. Go to Settings → Environments
  2. Click on pre-release, production, or patch-release
  3. View Deployment history:
  4. Who triggered the workflow
  5. Who approved/rejected
  6. When it was deployed
  7. Links to workflow runs
  8. Comments from reviewers

This creates a complete audit trail for compliance.

Warning: Only repository administrators can bypass environment protection rules.

If you need to bypass approval (emergency only):

  1. Go to Settings → Environments
  2. Select the environment
  3. Temporarily remove Required reviewers
  4. Run the workflow
  5. Immediately re-enable required reviewers

Better approach: Add yourself as an approved reviewer if needed.

Troubleshooting

Workflow stuck waiting: Check Actions tab for "Review deployments" button, verify you're a required reviewer

Cannot approve: Ensure you're listed as reviewer and didn't trigger the workflow yourself (if self-review prevented)

Environment not found: Verify environment names in workflow files match Settings → Environments exactly

Security Best Practices

Required Reviewers

Pre-release environment:

  • Minimum: 1 reviewer
  • Recommended: 1-2 reviewers
  • Should include: Project maintainers

Production environment:

  • Minimum: 2 reviewers
  • Recommended: 2-3 reviewers
  • Should include: Senior maintainers, security lead

Patch release environment:

  • Minimum: 1 reviewer
  • Recommended: 1-2 reviewers (can be same as pre-release)
  • Should include: Security lead (for security patches), maintainers
  • Note: Security patches should be expedited but still reviewed

Branch Protection

Combine environment protection with branch protection:

  1. Go to Settings → Branches
  2. Add rule for main branch:
  3. ✅ Require pull request reviews (at least 1)
  4. ✅ Require status checks to pass
  5. ✅ Require branches to be up to date

  6. ✅ Include administrators

  7. Add rule for release-* pattern (for patch release branches):

  8. ✅ Require pull request reviews (at least 1)
  9. ✅ Require status checks to pass
  10. ✅ Include administrators
  11. ✅ Restrict who can push (maintainers only)

This ensures:

  • Code is reviewed before merging
  • Tests pass before merging
  • Releases require additional approval
  • Patch releases are protected and audited

Audit Trail

GitHub automatically logs:

  • Who triggered the workflow
  • Who approved/rejected
  • When deployment occurred
  • Environment variables used
  • Workflow run details

Export deployment logs regularly for compliance:

  1. Go to Settings → Environments → [Environment]
  2. View deployment history
  3. Document approvals in release notes

Example Release Flow

Standard Release Flow

  1. Pre-Release: Trigger workflow → Reviewer approves → v0.2.0-rc1 created
  2. Testing: Test artifacts, fix issues, create new RC if needed
  3. Promotion: Trigger promote workflow → Multiple reviewers approve → v0.2.0 created
  4. Audit: All approvals logged in environment history

Patch Release Flow

  1. Security Fix: Vulnerability discovered in v0.1.0
  2. Create Branch: Create release-0.1 from v0.1.0 tag (if not exists)
  3. Apply Fix: Cherry-pick security fix to release branch
  4. Patch Release: Trigger patch workflow → Reviewer approves → v0.1.1 created
  5. Audit: Patch release approval logged in patch-release environment history

See Also