README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-ecs-codepipeline

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-ecs-codepipeline

# Badges to display
badges:
  - name: "GitHub Action Tests"
    image: "https://github.com/cloudposse/terraform-aws-ecs-codepipeline/workflows/test/badge.svg?branch=master"
    url: "https://github.com/cloudposse/terraform-aws-ecs-codepipeline/actions"
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-aws-ecs-codepipeline.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-ecs-codepipeline/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-ecs-codepipeline.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-ecs-codepipeline/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "terraform-aws-alb"
    description: "Terraform module to provision a standard ALB for HTTP/HTTP traffic"
    url: "https://github.com/cloudposse/terraform-aws-alb"
  - name: "terraform-aws-alb-ingress"
    description: "Terraform module to provision an HTTP style ingress rule based on hostname and path for an ALB"
    url: "https://github.com/cloudposse/terraform-aws-alb-ingress"
  - name: "terraform-aws-codebuild"
    description: "Terraform Module to easily leverage AWS CodeBuild for Continuous Integration"
    url: "https://github.com/cloudposse/terraform-aws-codebuild"
  - name: "terraform-aws-ecr"
    description: "Terraform Module to manage Docker Container Registries on AWS ECR"
    url: "https://github.com/cloudposse/terraform-aws-ecr"
  - name: "terraform-aws-ecs-alb-service-task"
    description: "Terraform module which implements an ECS service which exposes a web service via ALB."
    url: "https://github.com/cloudposse/terraform-aws-ecs-alb-service-task"
  - name: "terraform-aws-ecs-container-definition"
    description: "Terraform module to generate well-formed JSON documents that are passed to the aws_ecs_task_definition Terraform resource"
    url: "https://github.com/cloudposse/terraform-aws-ecs-container-definition"
  - name: "terraform-aws-lb-s3-bucket"
    description: "Terraform module to provision an S3 bucket with built in IAM policy to allow AWS Load Balancers to ship access logs."
    url: "https://github.com/cloudposse/terraform-aws-lb-s3-bucket"

# Short description of this project
description: |-
  Terraform Module for CI/CD with AWS Code Pipeline using GitHub webhook triggers and Code Build for ECS.

# How to use this project
usage: |2-

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using `bats` and `Terratest`, see [test](test).

  ### Trigger on GitHub Push

  In this example, we'll trigger the pipeline anytime the `master` branch is updated.
  ```hcl
  module "ecs_push_pipeline" {
    source = "cloudposse/ecs-codepipeline/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    name                  = "app"
    namespace             = "eg"
    stage                 = "staging"
    github_oauth_token    = "xxxxxxxxxxxxxx"
    github_webhooks_token = "xxxxxxxxxxxxxx"
    repo_owner            = "cloudposse"
    repo_name             = "example"
    branch                = "master"
    service_name          = "example"
    ecs_cluster_name      = "eg-staging-example-cluster"
    privileged_mode       = "true"
  }
  ```

  ### Trigger on GitHub Releases

  In this example, we'll trigger anytime a new GitHub release is cut by setting the even type to `release` and using the `json_path` to *exactly* match an `action` of `published`.

  ```hcl
  module "ecs_release_pipeline" {
    source = "cloudposse/ecs-codepipeline/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    name                        = "app"
    namespace                   = "eg"
    stage                       = "staging"
    github_oauth_token          = "xxxxxxxxxxxxxx"
    github_webhooks_token       = "xxxxxxxxxxxxxx"
    repo_owner                  = "cloudposse"
    repo_name                   = "example"
    branch                      = "master"
    service_name                = "example"
    ecs_cluster_name            = "eg-staging-example-cluster"
    privileged_mode             = "true"
    github_webhook_events       = ["release"]
    webhook_filter_json_path    = "$.action"
    webhook_filter_match_equals = "published"
  }
  ```

  (Thanks to [Stack Overflow](https://stackoverflow.com/questions/52516087/trigger-aws-codepipeline-by-github-release-webhook#comment91997146_52524711))


# Example usage
examples: |-
  Complete usage can be seen in the [terraform-aws-ecs-web-app](https://github.com/cloudposse/terraform-aws-ecs-web-app/blob/master/main.tf) module.

  ## Example Buildspec

  Here's an example `buildspec.yaml`. Stick this in the root of your project repository.

  ```yaml
  version: 0.2
  phases:
    pre_build:
      commands:
        - echo Logging in to Amazon ECR...
        - aws --version
        - eval $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email)
        - REPOSITORY_URI=$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$IMAGE_REPO_NAME
        - IMAGE_TAG=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7)
    build:
      commands:
        - echo Build started on `date`
        - echo Building the Docker image...
        - REPO_URI=$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$IMAGE_REPO_NAME
        - docker pull $REPO_URI:latest || true
        - docker build --cache-from $REPO_URI:latest --tag $REPO_URI:latest --tag $REPO_URI:$IMAGE_TAG .
    post_build:
      commands:
        - echo Build completed on `date`
        - echo Pushing the Docker images...
        - REPO_URI=$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$IMAGE_REPO_NAME
        - docker push $REPO_URI:latest
        - docker push $REPO_URI:$IMAGE_TAG
        - echo Writing image definitions file...
        - printf '[{"name":"%s","imageUri":"%s"}]' "$CONTAINER_NAME" "$REPO_URI:$IMAGE_TAG" | tee imagedefinitions.json
  artifacts:
    files: imagedefinitions.json
  ```

# How to get started quickly
#quickstart: |-
#  Here's how to get started...

# Other files to include in this README from the project folder
include:
  - "docs/targets.md"
  - "docs/terraform.md"

references:
  - name: "aws_codepipeline_webhook"
    description: "Provides a CodePipeline Webhook"
    url: "https://www.terraform.io/docs/providers/aws/r/codepipeline_webhook.html"

# Contributors to this project
contributors: []