Skip to content

docs(codepipeline): fix quickstart steps that don't work as written - #31

Open
joeymussalli wants to merge 1 commit into
trustabl:mainfrom
joeymussalli:docs/codepipeline-quickstart-fixes
Open

docs(codepipeline): fix quickstart steps that don't work as written#31
joeymussalli wants to merge 1 commit into
trustabl:mainfrom
joeymussalli:docs/codepipeline-quickstart-fixes

Conversation

@joeymussalli

Copy link
Copy Markdown

Each of these was checked against current AWS documentation.

The console quickstart never produces artifacts. Step 3 wires up an input artifact and stops there, but a CodeBuild action takes "0 to 5" output artifacts and they are what "make the artifacts that are defined in the CodeBuild buildspec file available to subsequent actions". With none declared, the artifacts: block in buildspec.yml has nowhere to go. A reader follows all four steps, sees the gate work, and finds that the SARIF and JSON this README promised them two paragraphs earlier do not exist anywhere.

The CLI quickstart's first command fails on a fresh account. The import-source-credentials call was a footnote three lines below create-project, labelled as a private-repo concern. Both parts are wrong. ProjectSource states "For source code in a GitHub repository ... You must connect your AWS account to your GitHub account", with no public-repo exemption, and the access-token guide puts the ordering the other way round: "After your account is connected with an access token, you can use create-project". An account that has never connected GitHub gets InvalidInputException: No Access token found on the first command of the block. Moved it to the top and dropped the private-repo framing.

The IAM policy cannot write the artifacts the same paragraph enables. The inline policy grants CloudWatch Logs only, and the very next sentence tells you to swap NO_ARTIFACTS for an S3 location. The CodeBuild service role is what writes to that bucket, so the moment you follow that advice UPLOAD_ARTIFACTS fails with AccessDenied -- a red build for a reason unrelated to the scan. Added the s3 policy alongside, and a note about KMS for an SSE-KMS bucket.

Two smaller notes:

  • Branch and repository detection cannot work in a pipeline-triggered build. CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook event that triggers the current build", CODEBUILD_SOURCE_REPO_URL "may be empty" when the build originates from CodePipeline, and a source artifact is an unzipped snapshot with no .git for the third fallback. So every report in this integration reads Repository: . / Branch: unknown. BRANCH is the fix and appears nowhere in the root README's inputs table.
  • SARIF_FILE and JSON_FILE cannot be repointed on their own: the script honours them but buildspec.yml collects the default filenames, so overriding either produces the file and then silently drops it.

Documentation only; no code changes.

Refs: https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodeBuild.html
https://docs.aws.amazon.com/codebuild/latest/userguide/access-tokens-github.html
https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html
https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html

Each of these was checked against current AWS documentation.

**The console quickstart never produces artifacts.** Step 3 wires up an input
artifact and stops there, but a CodeBuild action takes "0 to 5" output
artifacts and they are what "make the artifacts that are defined in the
CodeBuild buildspec file available to subsequent actions". With none declared,
the `artifacts:` block in buildspec.yml has nowhere to go. A reader follows all
four steps, sees the gate work, and finds that the SARIF and JSON this README
promised them two paragraphs earlier do not exist anywhere.

**The CLI quickstart's first command fails on a fresh account.** The
import-source-credentials call was a footnote three lines below create-project,
labelled as a private-repo concern. Both parts are wrong. ProjectSource states
"For source code in a GitHub repository ... You must connect your AWS account
to your GitHub account", with no public-repo exemption, and the access-token
guide puts the ordering the other way round: "After your account is connected
with an access token, you can use create-project". An account that has never
connected GitHub gets InvalidInputException: No Access token found on the first
command of the block. Moved it to the top and dropped the private-repo framing.

**The IAM policy cannot write the artifacts the same paragraph enables.** The
inline policy grants CloudWatch Logs only, and the very next sentence tells you
to swap NO_ARTIFACTS for an S3 location. The CodeBuild service role is what
writes to that bucket, so the moment you follow that advice UPLOAD_ARTIFACTS
fails with AccessDenied -- a red build for a reason unrelated to the scan.
Added the s3 policy alongside, and a note about KMS for an SSE-KMS bucket.

Two smaller notes:

- Branch and repository detection cannot work in a pipeline-triggered build.
  CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook
  event that triggers the current build", CODEBUILD_SOURCE_REPO_URL "may be
  empty" when the build originates from CodePipeline, and a source artifact is
  an unzipped snapshot with no .git for the third fallback. So every report in
  this integration reads `Repository: .` / `Branch: unknown`. BRANCH is the fix
  and appears nowhere in the root README's inputs table.
- SARIF_FILE and JSON_FILE cannot be repointed on their own: the script honours
  them but buildspec.yml collects the default filenames, so overriding either
  produces the file and then silently drops it.

Documentation only; no code changes.

Refs: https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodeBuild.html
      https://docs.aws.amazon.com/codebuild/latest/userguide/access-tokens-github.html
      https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html
      https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant