Roles

Rack Gateway defines five roles organized in a hierarchy. Each role includes specific permissions and may inherit permissions from other roles.

Role Hierarchy

The hierarchy uses inheritance: each role automatically includes all permissions from roles below it.

Viewer

Human Users

Purpose: Read-only access for monitoring and observability.

Attribute	Value
Label	Viewer
Inherits From	None
Description	Read-only access to apps, builds, processes, and rack status

Permissions

Permission	Description
convox:app:list	List all applications
convox:app:read	View application details
convox:process:list	List running processes
convox:process:read	View process details
convox:instance:list	List EC2/container instances
convox:instance:read	View instance details
convox:log:read	Stream application logs
convox:build:list	List builds
convox:build:read	View build details
convox:rack:read	View rack configuration
gateway:user:list	View the team directory
gateway:api_token:read	See API tokens an admin has issued to them

Every role

Every user, whatever their role, can view their own profile, list and sign out their own sessions, read their own audit trail, and manage their own MFA methods.

Use Cases

• Stakeholders: Product managers, executives viewing deployment status
• Support Teams: Customer support checking application health
• Auditors: External auditors reviewing system state
• Developers (Limited): Engineers who only need to observe, not modify

What Viewers Cannot Do

• Restart applications
• Execute commands in containers
• View environment variables (contain secrets)
• Create builds or deployments
• Modify any resources

---

Ops (Operations)

Human Users

Purpose: Operational access for incident response and debugging.

Attribute	Value
Label	Operations
Inherits From	Viewer
Description	Restart apps, manage processes, and view environments

Additional Permissions

Beyond all Viewer permissions:

Permission	Description
convox:app:restart	Restart application processes
convox:process:start	Start a process
convox:process:exec	Execute commands in containers
convox:process:terminate	Terminate a process
convox:release:list	List releases
convox:env:read	View environment variables

Use Cases

• On-Call Engineers: Incident response and debugging
• SRE Teams: Operational troubleshooting
• DevOps Engineers: Day-to-day operations without deployment access

Key Capability: Running Commands in Containers

convox:process:exec runs a command in a running process, and convox:process:start starts a one-off process:

rack-gateway exec <process-id> "cat /etc/hosts" -a myapp   # convox:process:exec
rack-gateway run web "rails console" -a myapp              # convox:process:start

Security Consideration

Container exec access is powerful. Users can potentially access secrets in the container’s environment or filesystem. Grant Ops role only to trusted engineers.

What Ops Cannot Do

• Create builds
• Promote releases to production
• Modify environment variables
• Create or delete applications
• Manage users or settings

---

Deployer

Human Users

Purpose: Full deployment access for engineers who ship code.

Attribute	Value
Label	Deployer
Inherits From	Ops
Description	Full deployment permissions including env updates

Additional Permissions

Beyond all Ops permissions:

Permission	Description
convox:build:create	Create new builds
convox:object:create	Upload build artifacts
convox:release:create	Create releases
convox:release:read	View release details
convox:release:promote	Promote releases to production
convox:env:set	Set environment variables
convox:app:update	Update application settings
gateway:deploy_approval_request:create	Request deploy approval
gateway:deploy_approval_request:read	View approval requests
gateway:api_token:create	Create API tokens for themselves
gateway:api_token:update	Edit their own API tokens
gateway:api_token:delete	Delete their own API tokens
convox:deploy:deploy_with_approval	Lets their CI tokens deploy with approval

Deployers can issue CI/CD tokens for their own pipelines. A token can’t hold more than the deployer’s role, and stops working if the deployer is demoted or locked.

Use Cases

• Software Engineers: Deploy code to production
• DevOps Engineers: Full deployment workflow
• Release Managers: Coordinate releases

Key Capability: Full Deployment

Deployers can execute the complete deployment workflow:

# Build from source
rack-gateway build -a myapp

# Or deploy directly (build + promote)
rack-gateway deploy -a myapp

# Update environment variables
rack-gateway env set API_KEY=secret -a myapp

# Promote a specific release
rack-gateway releases promote RABCDEF -a myapp

What Deployers Cannot Do

• Delete applications
• Manage users and roles
• Configure gateway settings
• Access other users’ audit logs
• Create or manage API tokens for other users

---

CI/CD

API Tokens Only

Purpose: Minimal permissions for automated deployment pipelines.

Attribute	Value
Label	CI/CD
Inherits From	None (standalone)
Description	Recommended scope for automation tokens (not assignable to human users)

Token-Only Role

The CI/CD role cannot be assigned to human users. It’s specifically designed for API tokens used in automated pipelines like CircleCI, GitHub Actions, or Jenkins.

Permissions

Permission	Description
convox:app:list	List applications
convox:app:read	View application details
convox:process:list	List processes
convox:process:read	View process details
convox:instance:list	List instances
convox:instance:read	View instance details
convox:rack:read	View rack info
gateway:deploy_approval_request:create	Request deploy approval
gateway:deploy_approval_request:read	View approval status
convox:deploy:deploy_with_approval	Deploy when approved

Use Cases

• CI/CD Pipelines: CircleCI, GitHub Actions, Jenkins
• Automated Testing: Integration test runners
• Deployment Automation: Infrastructure-as-code tools

Deploy Approval Integration

The CI/CD role is designed to work with Deploy Approvals:

1. CI/CD pipeline creates a deploy approval request
2. An admin reviews and approves it in the web UI or with rack-gateway deploy-approval approve (Slack posts the request with a link)
3. The CI/CD pipeline deploys with deploy_with_approval

# In CI/CD pipeline
rack-gateway deploy-approval request --app myapp --git-commit "$GIT_SHA" \
  --message "Deploy $GIT_SHA" --wait
rack-gateway deploy -a myapp

Why Not Use Deployer for CI/CD?

The Deployer role includes permissions CI/CD pipelines don’t need:

• Container exec (convox:process:exec) - Security risk in automation
• Environment variable access - Pipelines shouldn’t read production secrets
• Direct deployment - Bypasses approval workflow

---

Admin

Human Users

Purpose: Complete administrative access for platform administrators.

Attribute	Value
Label	Admin
Inherits From	All (wildcard)
Description	Complete access to all gateway operations

Permissions

Permission	Description
convox:*:*	All Convox operations
gateway:*:*	All Gateway operations
security:*:*	Security operations (rack TLS certificate refresh)

The wildcard permissions grant access to everything, including:

• All Convox operations (apps, builds, releases, etc.)
• User management (create, update, delete users)
• Role assignments
• Gateway settings and configuration
• Audit log access
• API token management for all users
• Destructive operations (delete apps, users)

Use Cases

• Platform Administrators: Full system management
• Security Team: Access reviews and incident investigation
• Initial Setup: Configuring the gateway for first use

Admin-Only Operations

Operation	Permission
Create users	gateway:user:create
Delete users	gateway:user:delete
Change user roles	gateway:user:update
View, edit or delete any user’s API tokens	gateway:api_token:manage
View other users’ details and sessions	gateway:user:read
View and export everyone’s audit logs	gateway:audit_log:read
List deploy approval requests and approve them	gateway:deploy_approval_request:list, :approve
Run processes with privileged options	convox:process:run_privileged
Change or remove protected env vars (--allow-protected, MFA on every change)	convox:env:set_protected
Delete applications	convox:app:delete
Configure gateway settings	gateway:setting_group:*

Limit Admin Access

Follow the principle of least privilege. Most teams should have only 2-3 admins. Regular engineers should use Deployer or Ops roles.

---

Role Comparison Matrix

Capability	Viewer	Ops	Deployer	CI/CD	Admin
View apps and processes	Yes	Yes	Yes	Yes	Yes
View logs and builds	Yes	Yes	Yes	No	Yes
View releases	No	Yes	Yes	No	Yes
View environment variables	No	Yes	Yes	No	Yes
Restart applications	No	Yes	Yes	No	Yes
Exec into containers	No	Yes	Yes	No	Yes
Create builds	No	No	Yes	No	Yes
Promote releases	No	No	Yes	No	Yes
Set environment variables	No	No	Yes	No	Yes
Request deploy approval	No	No	Yes	Yes	Yes
Deploy with approval (API tokens)	No	No	Own tokens	Yes	Yes
View team directory	Yes	Yes	Yes	No	Yes
View own profile, sessions and activity	Yes	Yes	Yes	No	Yes
Create API tokens for themselves	No	No	Yes	No	Yes
Manage users	No	No	No	No	Yes
View everyone’s audit logs	No	No	No	No	Yes
Delete applications	No	No	No	No	Yes
Configure settings	No	No	No	No	Yes

Choosing the Right Role

Next Steps

• Permissions - Complete permission reference
• Best Practices - Role assignment patterns