Deploying with GitHub Actions

Deploying with GitHub Actions

Once your project's Docker image builds and the incubator's Terraform declares your project's AWS resources, a GitHub Actions workflow in your own repository can deploy it: build the image, push it to the incubator's ECR, and redeploy your ECS service.

The incubator provides a template for that workflow: github-actions/workflow-configs/templates/deploy-to-aws.yml. Copy it into your repository as .github/workflows/deploy-to-aws.yml and fill in every line marked YOU MUST FILL THIS OUT. The comments in the file are the full instructions; this page explains where its values come from.

How the incubator's Terraform values are used

You fill in three things, and they are the same three values your project's Terraform already passes to the incubator modules. Everything the workflow touches in AWS is derived from them.

You fill in	Matches this in your project's Terraform
PROJECT	project_name — the HfLA project name, e.g. people-depot
APPLICATION_TYPE	application_type — backend, frontend or fullstack
the environment list	environment — one entry per environment you have, e.g. dev, stage, prod

The workflow uses	Built as	Declared by
IAM role it signs in as	incubator-cicd-<project>	cicd_integration
ECR repository it pushes to	<project>-<application_type>	ecr, via repository_name
Image tag	<environment>	the container_image you give the container module, e.g. ...:dev
ECS service it redeploys	<project>-<application_type>-<environment>	container

So for PeopleDepot's dev backend — people-depot, backend, dev — the workflow signs in as incubator-cicd-people-depot, pushes people-depot-backend:dev, and redeploys the people-depot-backend-dev service.

If any of those names do not exist, the workflow fails at that step. The usual cause is that the matching Terraform has not been added yet, or uses a name that does not follow the pattern. The role also only trusts the GitHub repository named in your cicd_integration module's repository_name, so the workflow cannot sign in from any other repository.

Running it

• On demand: Actions tab → deploy to aws → Run workflow, then pick a branch and an environment. Any branch can go to any environment in your list.
• Automatically on every push to a branch: make a second copy of the file for that branch. The steps are at the top of the template.

The image tag is the environment name and is overwritten on every deploy, so the service always runs whatever was deployed to that environment most recently.

Related

• AWS Resources — the generated Terraform documentation for everything the incubator runs, including the modules above.
• Container Permissions — what your running container is allowed to do in AWS, which is separate from what this deploy workflow is allowed to do.