> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.
> Learn about ACUL deployment workflow
# ACUL Deployment Workflow
To follow this workflow, make sure you have:
* An Auth0 development tenant configured with [Universal Login](docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
* An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications)
* [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) enabled in your Auth0 tenant.
* An AWS account with permissions to create IAM roles, S3 buckets, and configure CloudFront
* A GitHub repository containing your custom login screens
The ACUL production deployment workflow builds and deploys your ACUL screens and configures your tenant to use them. It uses GitHub Actions to:
* Build your screen asset bundles
* The workflow reads the [config/deploy\_config.yml](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/deploy_config.yml) file to determine which screens are marked for deployment.
* If deployment targets are found, the workflow builds your ACUL assets, by using Vite and comping the code into the `/dist` directory.
* Upload your assets to AWS S3
* The workflow securely authenticates with AWS using [OpenID Connect (OIDC)](docs/authenticate/protocols/openid-connect-protocol).
* It uploads the contents of the `/dist` directory to your S3 bucket.
* Configure your Auth0 tenant
* The workflow uses [Auth0 CLI](https://auth0.github.io/auth0-cli/) with a M2M application to configure the screens in your tenant.
* It maps each screen to the correct Auth0 screen using the [config/screen-to-prompt-mapping.js](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/screen-to-prompt-mapping.js) file.
* It updates the Auth0 screen customization settings to point to your assets at CloudFront CDN.
Once configured, a `git push` to the `main` branch of your project starts the GitHub workflow.
To read a complete example of the ACUL production deployment workflow, read [ACUL GITHUB ACTIONS](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/GITHUB_ACTIONS.md) on Github.
### 1. Auth0 configuration
Create a [Machine-to-Machine](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) application to grant permissions to the GitHub workflow to update your tenant settings.
1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications).
2. Select **Create Application**.
3. Select **Machine to Machine Applications**.
4. Under **Name**, add a descriptive name, for example: `GitHub ACUL Deployment`.
5. Select **Create**.
6. Under **Authorize Machine to Machine Application**, select **Auth0 Management API**.
7. Select these specific permissions:
* `read:branding`
* `update:branding`
* `read:prompts`
* `update:prompts`
* `read:custom_domains`
8. Select **Authorize**.
9. Navigate to the **Settings** tab and note down:
* `Domain`
* `Client ID`
* `Client Secret`
### 2. Upload and serve your assets with Amazon web services
To upload and serve your assets, you need an AWS S3 bucket and to set CloudFront as the CDN.
* **Create an AWS S3 Bucket**. Block all public access so this bucket is private. This private bucket stores your assets.
* **Set Up a CloudFront Distribution**. This CDN securely serves your assets. It should be configured to use your S3 bucket as its `Origin` using Origin Access Control (OAC).
### 3. Create an AWS IAM role for GitHub Action
Create an **IAM Role** in AWS to grant GitHub Actions permission to upload files to AWS S3.
* This IAM role must use Web Identity (OIDC), trusting `token.actions.githubusercontent.com`.
* The role needs a policy granting `s3:PutObject`, `s3:DeleteObject`, and `s3:ListBucket` permissions on your S3 bucket.
### 4. Configure your GitHub repository
To configure your GitHub repository:
1. Navigate to **GitHub > Settings**.
2. Select **Secrets and Variables** and then **Actions**.
3. Select **New repository secret**.
Add the following repository secrets:
* `AWS_S3_ARN`: The ARN of the IAM role you created.
* `S3_BUCKET_NAME`: The name of your S3 bucket.
* `AWS_REGION`: The region where your S3 bucket is located. For example, `us-east-1`.
* `S3_CDN_URL`: Your CloudFront distribution's domain name. Do not add a trailing slash. For example, [https://d1234abcdef.cloudfront.net](https://d1234abcdef.cloudfront.net).
* `AUTH0_DOMAIN`: Your Auth0 tenant domain.
* `AUTH0_CLIENT_ID`: The Client ID from your M2M application.
* `AUTH0_CLIENT_SECRET`: The Client Secret from your M2M application.
### 5. Configure your deployment
You can control which screens are deployed by editing the configuration files located in the `.github/config/` directory:
* [`config/deploy_config.yml`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/deploy_config.yml): Your main control panel. Set a screen to `true` to deploy it or `false` to skip it.
* [`config/screen-to-prompt-mapping.js`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/screen-to-prompt-mapping.js): Maps your internal screen directory names. Example: `mfa-sms-challenge` to the official Auth0 prompt name `mfa-sms`.
* [`config/context-configuration.js`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/context-configuration.js): Defines Auth0 context data. Example: branding settings should be made available to your custom screens.