Private Package Repositories

Stackery supports installing packages from public repositories during the build process for Function resources when using the CodeBuild build strategy. This includes public repositories like npm for Node.js functions and PyPI for Python functions. Stackery can also be configured to install packages from private repositories, such as GitHub Packages.

Private Repository Access

Private package repositories require authentication using API keys. This section will explain how to manage API keys so they are stored in a safe location and retrieved at build time.

1. Upgrade the Stackery Role. The Stackery Role must be version 1.25.0 or later in AWS accounts where private package repositories will be used in deployments. See Updating Stackery Role for instructions on how to update the Stackery Role.

2. Create an API key. Follow your repository provider to generate a private API key. For example, GitHub repositories require a personal access token, which can be created following their tokens documentation.

3. Create an AWS KMS Customer Managed Key (CMK) for encryption. AWS Secrets Manager, which we use to store the API key, has a default KMS key it uses for encryption. Unfortunately, default KMS keys cannot be used when accessing secrets across AWS accounts. To support cross-account access we'll create a new customer key:

   $ aws kms create-key --description 'Key to encrypt private repository API keys for Stackery' --policy "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":[\"kms:Decrypt\",\"kms:DescribeKey\"],\"Resource\":\"*\",\"Condition\":{\"StringEquals\":{\"aws:PrincipalOrgID\":\"`aws organizations describe-organization --query Organization.Id --output text`\"},\"ArnLike\":{\"aws:PrincipalArn\":[\"arn:aws:iam::*:role/stackery/stackery-factory-role\",\"arn:aws:iam::*:role/stackery/stackery-deployer\"]}}},{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::`aws sts get-caller-identity --query Account --output text`:root\"},\"Action\":\"kms:*\",\"Resource\":\"*\"}]}"
   

   If you need to use a specific AWS credential profile and/or region you should export the AWS_PROFILE and AWS_REGION environment variables before running the AWS commands in this document. Many commands have substitutions embedded within to fetch your AWS Account and/or Organization IDs. Exporting the profile and region as environment variables ensures they are used for both the embedded substitutions and the parent commands.

   Note the key's ARN in the output, it should look like: arn:aws:kms:us-east-1:012345678901:key/8e7be4ac-a392-4bdd-8ff8-1ab1683de829

4. Store the API key in AWS Secrets Manager. The following command will create a new AWS Secrets Manager Secret which stores your API key in encrypted form using the KMS CMK created above.

   $ aws secretsmanager create-secret --name /stackery/ghpackagerepotoken --description 'GitHub Packages Personal Access Token' --secret-string '<API key>' --kms-key-id '<KMS key ARN from previous step>'
   

   Note the secret's ARN in the output, it should look like: arn:aws:secretsmanager:us-east-1:012345678901:secret:/stackery/ghpackagerepotoken-hCsqhY

5. Add a permission to retrieve the API key. Now that the API key is stored in AWS Secrets Manager we need to provide the Stackery CodeBuild environment with permissions to read it. Run the following command to provide read access to the key for the AWS IAM Roles used in Stackery CodeBuild environments across all AWS accounts in the same AWS Organization:

   $ aws secretsmanager put-resource-policy --secret-id /stackery/ghpackagerepotoken --resource-policy "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"secretsmanager:GetSecretValue\",\"Resource\":\"*\",\"Condition\":{\"StringEquals\":{\"aws:PrincipalOrgID\":\"`aws organizations describe-organization --query Organization.Id --output text`\"},\"ForAllValues:StringEquals\":{\"secretsmanager:VersionStage\":\"AWSCURRENT\"},\"ArnLike\":{\"aws:PrincipalArn\":[\"arn:aws:iam::*:role/stackery/stackery-factory-role\",\"arn:aws:iam::*:role/stackery/stackery-deployer\"]}}}]}"
   

6. Retrieve API key in pre-build hook. Add a pre-build hook to each stack needing private package repository access by creating the file deployHooks/stackery.prebuild.npmrc to retrieve the API key and place it in the appropriate location (in this example we use it to set up an npm configuration for GitHub Packages access):

   #!/bin/bash -e
   # Provide the AWS Secrets Manager Secret ARN from step 4 here
   SECRET_ARN=<secret ARN>
   
   echo "Fetching private package repo API key from secret '${SECRET_ARN}'"
   
   # Parse AWS region from secret ARN
   IFS=: read -ra ARN_PARTS <<< "${SECRET_ARN}"
   REGION="${ARN_PARTS[3]}"
   
   echo "//npm.pkg.github.com/:_authToken=`aws secretsmanager get-secret-value --region "${REGION}" --secret-id "${SECRET_ARN}" --query SecretString --output text`" >> ~/.npmrc
   

   When the stack is prepared the pre-build hook will retrieve the API key from AWS Secrets Manager and set up npm to use it when pulling packages from the GitHub packages private repository. When the build phase is run, private packages will be installable by Node.js runtime functions.