Skip to main content

Machine users

Gruntwork recommends using CI users in Gruntwork Pipelines, separate from human users in your organization. Using a CI user ensures that a workflow won't break due to an employee leaving your company. Further, using CI users allow you to apply granular permissions that may normally be too restrictive for a normal employee to do their daily work.

info

This guide will take approximately 30 minutes to complete.

Creating machine users​

Gruntwork Pipelines requires using two machine users; one with the ability to open pull requests and run workflows on your behalf and another that can only read code from GitHub. Restrictive permissions are then applied to each user to limit them to only perform the required actions to accomplish their tasks. This means that in order to actually run a pipeline job, both users must be involved at separate stages.

We’ll refer to this user as ci-user and ci-read-only-user, but you may name them anything you like. These users must:

  1. Both be members of your GitHub Organization
  2. Both be members of your team in Gruntwork’s GitHub Organization (See instructions on inviting a user to your team and linking the user’s GitHub ID to Gruntwork)

Storing secrets​

During this setup, you will need to generate and securely store three GitHub tokens for two GitHub users. You will need a temporary location for these sensitive values between generating them and storing them in GitHub Actions. Do so according to your company's recommended security best practices (e.g., do not store them in Slack, a sticky note, etc., during this exercise.)

note

Your organization is required to rotate the GitHub tokens and update all GitHub secrets that use them.

ci-user​

The ci-user orchestrates workflows, can open pull requests from automated code generation, and leave comments on pull requests. This user should have two GitHub Fine Grained Personal Access Tokens (PAT)s with the following permissions.

First, invite the ci-user to both your infrastructure-live and infrastructure-pipelines repositories with collaborator access. Then, create the following access tokens in the ci-user's GitHub account:

  1. INFRA_LIVE_ACCESS. This is a fine-grained GitHub access token and will be used to grant GitHub Actions access to clone your infrastructure-live repository, open PRs, and create comments & issues.

    This token must have the following permissions to your infrastructure-live repo in your GitHub Organization:

    • Content read & write access
    • Issues read & write access
    • Metadata read access
    • Pull requests read & write access
    • Workflows read & write access

    INFRA_LIVE_ACCESS PAT ConfigurationINFRA_LIVE_ACCESS PAT Configuration

  2. PIPELINES_DISPATCH. This token will be used to grant GitHub Actions, in your infrastructure-live repository, permission to trigger workflows in your infrastructure-pipelines repository.

    This token must have:

    • Actions read & write access
    • Contents read only access
    • Metadata read access

    PIPELINES_DISPATCH PAT ConfigurationPIPELINES_DISPATCH PAT Configuration

  3. MANAGE_REPOS. This token will be used to create new infra-live-<TEAM-NAME> repositories in your GitHub Organization when vending delegated team accounts.

    This token must have the following permissions to all repositories the ci-user has access to:

    • Administration read & write access
    • Contents read & write access
    • Metadata read access
    • Pull requests read & write access
    • Workflows read & write access

    and Organization permissions to:

    • Secrets read & write access

    MANAGE_REPOS PAT ConfigurationMANAGE_REPOS PAT Configuration

  4. PIPELINES_BOOTSTRAP. This token will be used to grant GitHub Actions permission to create open PRs and create comments in your infrastructure-pipelines repository in your GitHub Organization. This is only required during the bootstrap process of the pipelines repository and should be removed immediately after.

    This token must have:

    • Contents read & write access
    • Metadata read access
    • Pull requests read & write access
    • Workflows read & write access

    PIPELINES_BOOTSTRAP PAT ConfigurationPIPELINES_BOOTSTRAP PAT Configuration

ci-read-only-user​

This user is created to pull down Terraform/OpenTofu code, but not to apply it. The ci-read-only-user is used clone infrastructure-live and in Terragrunt actions to access Gruntwork Library modules and your own infrastructure-modules repository or any custom module repositories that are private.

The ci-read-only-user should have a single classic token Personal Access Tokens (PAT) with read permissions. Classic PATs have coarse granularity, we recommend putting this user in a GitHub team that only has READ access to infrastructure-live and any relevant module repositories in your own GitHub Organization. By adding this user to the Gruntwork Developer portal, they will automatically gain access to the Gruntwork Library.

Invite ci-user-read-only to your infrastructure-live repository with collaborator access. Create the following token for the ci-read-only-user:

  1. GRUNTWORK_CODE_ACCESS. This token will be used to manage access to Gruntwork resources during GitHub Action runs.

This token must have repo scopes.

GRUNTWORK_CODE_ACCESS PAT ConfigurationGRUNTWORK_CODE_ACCESS PAT Configuration

The expiration of this token is up to you and the security posture of your organization, Gruntwork recommend 90 days to avoid having to regularly rotate a token and secrets.

Invite both machine users to Gruntwork​

Ensure both of these machine users are members of your team in Gruntwork’s GitHub Organization (See instructions on inviting a user to your team and linking the user’s GitHub ID to Gruntwork)

Configure secrets for GitHub Actions​

info

The recommended path for storing secrets in GitHub Actions is with Organization level secrets, however not all GitHub plans support repository specific Organization secrets. If this is the case for your GitHub organization, you should use Repository level secrets.

info

Since this guide implements secrets that are scoped to specific repositories, anytime a new infrastructure-live or infrastructure-pipelines repository is created, the permissions for these tokens will need to be updated.

  1. Navigate to your top level GitHub Organization and select the Settings tab.

  2. From the navigation bar on the left side, select Secrets and variables then select Actions.

  3. Using the New organization secret option, add the following secrets:

  • GRUNTWORK_CODE_ACCESS_TOKEN

    1. This should be assigned the GRUNTWORK_CODE_ACCESS token generated by the ci-read-only-user in the secrets section as its value.

    2. Repository access. Select the Private Repositories option.

  • PIPELINES_DISPATCH_TOKEN

    1. This should be assigned the PIPELINES_DISPATCH token generated by the ci-user in the secrets section as its value.

    2. Repository access. Select the Private Repositories option.

    info

    GRUNTWORK_CODE_ACCESS & PIPELINES_DISPATCH tokens are made available to all private repositories so that every vended infra-live-team-* repository automatically has access to these secrets. The infrastructure-pipelines repository mitigates the misuse of these secrets by maintaining a list of allowed repositories than can trigger workflows in it using the PIPELINES_DISPATCH token.

    The alternative of granting access to these secrets during the vending process has various drawbacks (e.g., only works for GitHub owners, requires a new machine user, a new PAT, etc).

  • INFRA_LIVE_ACCESS_TOKEN

    1. This should be assigned the INFRA_LIVE_ACCESS token generated by the ci-user in the secrets section as its value.

    2. Repository access. Using the Selected repositories option select both the infrastructure-live and infrastructure-pipelines repositories.

  • MANAGE_REPOS_TOKEN

    1. This should be assigned the MANAGE_REPOS token generated by the ci-user in the secrets section as its value.

    2. Repository access. Using the Selected repositories option select only the infrastructure-pipelines repository.

  • PIPELINES_BOOTSTRAP_TOKEN

    1. This should be assigned the PIPELINES_BOOTSTRAP token generated by the ci-user in the secrets section as its value.

    2. Repository access. Using the Selected repositories option select only the infrastructure-pipelines repository.

danger

After the bootstrap process is complete, you should delete the following tokens for security purposes:

- The `PIPELINES_BOOTSTRAP` Personal Access Token from the `ci-user` GitHub account
- The `PIPELINES_BOOTSTRAP_TOKEN` GitHub Actions secret from the `infrastructure-pipelines` repository
info

For additional information on creating and using Github Actions Organization secrets, please refer to the GitHub Documentation.