Skip to main content
Sponsor @cloudposse

Setup GitOps with GitHub Actions

Quick Start​

Steps
1. Verify Identity requirements
2. Expand GitHub OIDCatmos workflow deploy/github-oidc-provider -f gitops
2. Vendoratmos workflow vendor -f gitops
3. Deployatmos workflow deploy/gitops -f gitops

Requirements​

1 Self-Hosted Runners​

Although not required, we recommend first deploying Self-Hosted GitHub runners if you need to manage any resources inside of a VPC (e.g. RDS Users). For more information on setting up runners, see the Philips Labs GitHub Runners or the GitHub Action Runner Controller (EKS) setup documentation.

If you do not wish to use Self Hosted runners, simply change the runs-on option for all included workflows in .github/workflows

2 Set Up GitHub Variables​

The gitops stack config depends on the following GitHub variables:

ATMOS_VERSION
The version of Atmos to use
ATMOS_CONFIG_PATH
The path to the Atmos config file

Please set the following GitHub variables in the repository settings:

  1. Open the repository settings
  2. Set variable ATMOS_VERSION to the 1.63.0 value
  3. Set variable ATMOS_CONFIG_PATH to the ./rootfs/usr/local/etc/atmos/ value

3 Authentication Prerequisites​

The GitHub Action workflows expect both the gitops and planners AWS Teams to be properly setup and connected to GitHub OIDC. Both of these components should already be deployed with aws-teams/aws-team-roles and github-oidc-provider respectively, but github-oidc-provider will likely need to deployed to several additional accounts. Verify the following to complete the authentication prerequisites.

Trusted GitHub Repos

By default in the Reference Architecture, the trusted_github_repos input is commented out for aws-teams. Now is the time to uncomment those lines. Follows the tasks below. Please see stacks/catalog/aws-teams.yaml

  • The gitops and planners Teams are defined and deployed by aws-teams.
  • Both teams have trusted relationships with the infrastructure repo via trusted_github_repos. Capitalization matters! In the reference architecture, these values are initially commented out and will need to be updated with your specific repository information: 
    components:
      terraform:
        aws-teams:
          vars:
            trusted_github_repos:
              gitops:
                - "acme/infra:main"
              planners:
                - "acme/infra"
  • The aws-team-roles default catalog allows the gitops team to assume the terraform role, including anywhere aws-team-roles is overwritten (plat-dev and plat-sandbox)
  • Similarly, the planners team can assume the planner role in aws-team-roles to plan Terraform only.
  • tfstate-backend allows both teams to assume the default access role from the core-identity account
  • github-oidc-provider is deployed to every account that GitHub will be able to access. This should be every account except root.
  • The workflows have adequate permission
GitHub Workflow Permissions

In order to assume GitHub OIDC roles, a workflow needs the following:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

In order to assume GitHub OIDC roles and manage Github Issues, a workflow needs these permissions:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: write # This is required for actions/checkout and updating Issues
  issues: write # This is required for creating and updating Issues

How To Setup​

1 Vendor Components​

The gitops stack config depends on two components that may already exist in your component library (s3-bucket and dynamodb) and adds one new component (gitops) to manage the GitHub OIDC access. Vendor these components either with the included Atmos Workflows or using Atmos Vendoring.

vendor:
These are the commands included in the vendor workflow in the examples/snippets/stacks/workflows/gitops.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

2 Deploy GitOps Prerequisites​

Deploy the GitOps prerequisite components, gitops/s3-bucket, gitops/dynamodb, and gitops with the following workflow

deploy/gitops:
These are the commands included in the deploy/gitops workflow in the examples/snippets/stacks/workflows/gitops.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

3 Reapply aws-teams​

Now we need to reapply aws-teams to add the trusted GitHub repositories to gitops and planners.

Uncomment or add the trusted_github_repos input:

# stacks/catalog/aws-teams.yaml
components:
  terraform:
    aws-teams:
      vars:
        trusted_github_repos:
          gitops:
            - "acme/infra:main"
          planners:
            - "acme/infra"

Run the following command to apply:

Use a Privileged Role

aws-teams is a sensitive component deployed to the core-identity account and therefore needs to be applied with a role or user with access to the account. For example use the managers AWS Team or the SuperAdmin user.

atmos terraform apply aws-teams -s core-gbl-identity

And that's it! Now you can try creating a new pull request. If properly configured, you should see GitHub Actions kick off Atmos Terraform Plan.

Tips

  1. Enable GitHub Actions support for any component by enabling settings.github.actions_enabled: true and let the workflow handle the rest. Keep in mind this setting is likely enabled by default for your organization stack configuration, stacks/catalog/acme/_defaults.yaml
  2. The roles created by aws-teams or gitops should already be included in your workflows. Verify these roles match the env settings in .github/workflows/atmos-terraform-*
  3. You do not need to create a GitHub App or complete additional steps to trigger these workflows