> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastfoundation.nimble.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Github Actions

> Set up GitHub Actions workflows and environments for automated application deployment

## Why GitHub Environments?

GitHub Environments allow you to securely separate deployments between **staging** and **production**.

<CardGroup cols={2}>
  <Card title="Security" icon="shield">
    Store environment-specific secrets and variables
  </Card>

  <Card title="Protection" icon="lock">
    Require approvals for sensitive environments
  </Card>

  <Card title="Isolation" icon="layer-group">
    Clearly separate staging and production deployments
  </Card>

  <Card title="Flexibility" icon="gear">
    Update settings without changing code
  </Card>
</CardGroup>

***

## Required Environments

Set up your environments in your GitHub repository, we will use two in this guide:

<AccordionGroup>
  <Accordion title="Staging">
    * **Branch**: `staging`
    * **Protection**: Optional (review recommended)
    * **Purpose**: Pre-production testing
  </Accordion>

  <Accordion title="Production">
    * **Branch**: `production`
    * **Protection**: Required reviewers + branch protection
    * **Purpose**: Live production environment
  </Accordion>
</AccordionGroup>

***

## Variable Hierarchy

Understanding GitHub Actions variable precedence:

1. **Repository Variables** (lowest precedence) - Shared across all environments
2. **Environment Variables** (highest precedence) - Override repository variables
3. **AWS Secrets Manager** - Environment variables fetched dynamically during build

<CodeGroup>
  ```yaml Example Hierarchy theme={null}
  # Repository variable:
  APP_NAME: your-app-name  # Used in all environments

  # Environment variable (if set):
  APP_NAME: your-app-name-dev  # Would override repository variable for this environment

  # Environment-specific secret ARN:
  ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:123456789:secret:staging/your-app-name/cicd-env-ABC123
  ```
</CodeGroup>

***

## Step-by-Step Setup

### 1. Create GitHub Environments

1. Open your repository in GitHub
2. Go to **Settings → Environments**
3. Click **New environment**
4. Create: `staging` and `production`

***

### 2. Configure Repository Variables

Go to **Settings → Secrets and variables → Actions → Variables** and add:

<CodeGroup>
  ```yaml Repository Variables theme={null}
  # Application Configuration
  APP_NAME: your-app-name

  # Manifests Repository (shared across environments)
  MANIFEST_REPO_PK_SSM_NAME: /infrastructure/development/deployKey/deployer/repo/manifests/private_key
  MANIFEST_REPO_SSH_URL: git@github.com:your-org/manifests.git
  MANIFEST_REPO_ROOT_FOLDER: manifests
  ```
</CodeGroup>

### 3. Configure Environment-Specific Variables

For each environment, go to Environment → Variables and add:

<CodeGroup>
  ```yaml Staging Environment theme={null}
  # AWS Configuration
  AWS_DEPLOYER_ROLE_ARN: arn:aws:iam::ACCOUNT_ID:role/deployer_staging_your-app-name

  # ECR Repository
  ECR_REPOSITORY: staging/frontend/your-app-name

  # Environment Variables Secret
  ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:staging/your-app-name/cicd-env-ABC123
  ```

  ```yaml Production Environment theme={null}
  # AWS Configuration
  AWS_DEPLOYER_ROLE_ARN: arn:aws:iam::ACCOUNT_ID:role/deployer_production_your-app-name

  # ECR Repository
  ECR_REPOSITORY: production/frontend/your-app-name

  # Environment Variables Secret
  ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:production/your-app-name/cicd-env-ABC123
  ```
</CodeGroup>

### 4. Configure Environment Secrets

For each environment, at Environment → Secrets, add:

<CodeGroup>
  ```yaml Environment Secrets theme={null}
  # Notifications
  SLACK_HOOK: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
  ```
</CodeGroup>

### 5. Set Up Protection Rules

#### Staging Environment

* **Deployment branches**: `staging`
* **Required reviewers**: 1 (optional)
* **Wait timer**: None

#### Production Environment

* **Branches**: `production`
* **Required reviewers**: 2+ (recommended)
* **Wait timer**: 5 minutes (optional)

## AWS Secrets Manager Configuration

Environment variables are stored in AWS Secrets Manager.

### Secret Name Pattern

```
{environment}/{application}/cicd-env
```

### Example Secret Values

<CodeGroup>
  ```env Staging Secret theme={null}
  VITE_ENV=staging
  VITE_SENTRY_ENABLED=true
  VITE_STICKY_SUB_DOMAIN=your-app-staging
  # ... other staging-specific values
  ```

  ```env Production Secret theme={null}
  VITE_ENV=production
  VITE_SENTRY_ENABLED=true
  VITE_STICKY_SUB_DOMAIN=your-app
  # ... other production values
  ```
</CodeGroup>

## Deployment Flow

* **Automatic Deployments**
  * **Push to `staging`** → Deploys to staging environment
  * **Push to `production`** → Deploys to production (with approvals)

* **Manual Deployments**
  * Trigger deployments via GitHub Actions UI
  * Useful for hotfixes or rollbacks

## Required AWS Resources

<AccordionGroup>
  <Accordion title="SSM Parameters">
    The CI/CD pipeline needs to update your **manifests repository** during deployments.\
    To enable this, it fetches an SSH private key stored as an AWS SSM (Systems Manager) parameter.

    * `/infrastructure/development/deployKey/deployer/repo/manifests/private_key` → SSH key used by the pipeline to push changes into the manifests repo

    <Note>
      If you are using **Fast Foundation**, all of the resources below will be created **automatically** and will already be available in AWS.
    </Note>
  </Accordion>

  <Accordion title="IAM Roles">
    * `deployer_staging_your-app-name`
    * `deployer_production_your-app-name`

    **Required Permissions**: Each role needs access to:

    * ECR (push/pull images)
    * Secrets Manager (read environment variables)
    * SSM (read SSH keys)
  </Accordion>

  <Accordion title="ECR Repositories">
    * `staging/frontend/your-app-name`
    * `production/frontend/your-app-name`
  </Accordion>

  <Accordion title="AWS Secrets Manager">
    * `staging/your-app-name/cicd-env` (Staging environment variables)
    * `production/your-app-name/cicd-env` (Production environment variables)
  </Accordion>
</AccordionGroup>

## Security Best Practices

<Check>
  **CI/CD Best Practices**

  * Use least privilege IAM roles for each environment
  * Store environment variables in AWS Secrets Manager (encrypted)
  * Require approvals for production deployments
  * Protect the `production` branch from direct pushes
</Check>

## Next Steps

Once CI/CD is configured, continue to [Monitor Deployment](/application-creation/5-monitor-deployment) to track and verify rollouts.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Permission Denied in GitHub Actions">
    * Verify AWS deployer role ARN
    * Ensure the role has required permissions
    * Confirm trust policy allows GitHub OIDC federation
  </Accordion>

  <Accordion title="Secret Not Found">
    * Check ARN in environment variables
    * Verify secret exists in AWS Secrets Manager
    * Confirm role permissions allow secret read
  </Accordion>

  <Accordion title="ECR Push/Pull Errors">
    * Verify ECR repository URL and region
    * Ensure role has ECR permissions
    * Confirm repository exists
  </Accordion>

  <Accordion title="Manifest Repository Access Issues">
    * Validate SSH URL and SSM key parameter
    * Check role can access SSM key
    * Ensure repo is accessible via SSH
  </Accordion>
</AccordionGroup>