> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# studion/rollout

Build applications and deploy them to AWS using best practices. Tailored for use within Studion pipelines.


## Jobs

### build_and_push_server_to_aws_ecr

Build a Docker image and securely push it to AWS ECR using OIDC authentication. Out-of-the-box comprehensive security scanning with controls for code analysis, vulnerability detection, and compliance checks. Built on `circleci/aws-ecr`, `circleci/aws-cli`, `circleci/node`, and `studion/security` orbs.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `account_id` | string | ${AWS_ACCOUNT_ID} | The ID of the associated AWS account. |
| `after_checkout` | steps | [object Object] | The list of steps to execute after code checkout. Runs before any out-of-the-box security feature.
 |
| `before_build` | steps | [object Object] | The list of steps to execute before Docker image build. Runs after out-of-the-box security tools installation and code scanning, if enabled.
 |
| `before_push` | steps | [object Object] | The list of steps to execute before pushing image to ECR. Runs after out-of-the-box image scanning and SBOM generation.
 |
| `build_args` | string |  | Additional arguments to pass to the Docker build command. For multi-line arguments use Folded Block Style (build_args: >-).
 |
| `build_dir` | string | . | The path to the directory containing the build context. All security scans for code and dependencies use this as the root directory.
 |
| `dockerfile_dir` | string | . | The path to the directory containing the Dockerfile. Used as the scanning target for Dockerfile misconfiguration scanning.
 |
| `region` | string | ${AWS_DEFAULT_REGION} | The target AWS region. |
| `repo_name` | string |  | The name of the target AWS ECR repository. Created if it does not exist.
 |
| `role_arn` | string | ${AWS_ROLE_ARN} | The ARN of the IAM role that the job will assume. |
| `security` | enum | setup_and_run_all | Choose one of the available security configurations to run:
• `setup`: Install security tools only, no scans
• `setup_and_run_all`: Full security suite, code scan, image scan, and SBOM generation
• `setup_and_run_app_scan`: Code-only security checks, secrets, vulnerabilities, and misconfigurations
• `setup_and_run_img_scan`: Image-only security checks, vulnerabilities and secrets in built image
• `setup_and_run_sbom_tool`: Generate Software Bill of Materials (SBOM) only
• `skip`: Disable all security features
Note: Available security configurations are opinionated and non-customizable.
For custom security workflows, use `setup` or `skip` and implement in hooks (e.g. `before_build`).
 |
| `tags` | string | ${CIRCLE_SHA1},latest | Comma delimited list of tags to apply to the built image. By default, the SHA1 hash of the last commit and "latest".
 |

## Examples

### server_build_and_push

The "build_and_push_server_to_aws_ecr" job builds a Docker image, authenticates the job
with AWS using OIDC identity tokens, and pushes the image to ECR. As a part of this process,
various out-of-the-box security controls are executed against code, dependencies and image.
In the end, Software Bill of Materials (SBOM) is generated.
By default, the SHA1 hash of the latest commit and the "latest" string are used as a tag for
the image, while the AWS account, role, and region are sourced from the environment.


```yaml
version: '2.1'
orbs:
  rollout: studion/rollout@x.y.z
workflows:
  build_and_push_server:
    jobs:
      - rollout/build_and_push_server_to_aws_ecr:
          path_to_build_dir: ~/app/src
          path_to_dockerfile: ~/app
          repo_name: my-app
```

### server_build_and_push_custom_security

The available security configurations may not suite every project due to their
opinionated nature. In such cases, it is easy to bypass them and provide custom
security configurations.
Custom security configurations need to be implemented as series of steps at
specific points, (a) after code checkout - "after_checkout", (b) before Docker
image build - "before_build", and (c) before image push to ECR - "before_push".


```yaml
version: '2.1'
orbs:
  rollout: studion/rollout@x.y.z
  security: studion/security@x.y.z
workflows:
  build_and_push_server:
    jobs:
      - rollout/build_and_push_server_to_aws_ecr:
          before_build:
            - security/detect_secrets:
                mode: dir
                source: ~/app
            - security/analyze_code:
                full_scan: true
                verbose: true
            - security/scan_dependencies:
                scan_command: npm audit --audit-level=critical --omit=dev
            - security/scan_dockerfile:
                dockerfile_dir: ~/app
                severity: CRITICAL
          before_push:
            - security/assess_image:
                image: ${BUILD_IMAGE_NAME_WITH_TAG}
                scanners: vuln
                severity: critical
            - security/generate_sbom:
                exclude: /etc /usr
                image: ${BUILD_IMAGE_NAME_WITH_TAG}
          path_to_build_dir: ~/app/src
          path_to_dockerfile: ~/app
          repo_name: my-app
          security: setup
```