{"id":19373577,"url":"https://github.com/aws-actions/aws-codebuild-run-build","last_synced_at":"2025-10-19T22:14:27.354Z","repository":{"id":38426665,"uuid":"232921110","full_name":"aws-actions/aws-codebuild-run-build","owner":"aws-actions","description":"Run an AWS CodeBuild project as a step in a GitHub Actions workflow job.","archived":false,"fork":false,"pushed_at":"2024-12-05T19:06:44.000Z","size":11637,"stargazers_count":282,"open_issues_count":27,"forks_count":141,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-13T23:52:22.894Z","etag":null,"topics":["aws","aws-codebuild","codebuild","continuous-integration","devops","github-actions","serverless"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/codebuild","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-actions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-09T22:49:24.000Z","updated_at":"2025-04-11T03:23:40.000Z","dependencies_parsed_at":"2024-02-19T23:31:47.630Z","dependency_job_id":"2430c5a2-57f9-40e2-84ed-abf7563cb50f","html_url":"https://github.com/aws-actions/aws-codebuild-run-build","commit_stats":{"total_commits":128,"total_committers":36,"mean_commits":"3.5555555555555554","dds":0.84375,"last_synced_commit":"287d617e49bf7a4b372293628d53be1fcd9d17f9"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-actions%2Faws-codebuild-run-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-actions%2Faws-codebuild-run-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-actions%2Faws-codebuild-run-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-actions%2Faws-codebuild-run-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-actions","download_url":"https://codeload.github.com/aws-actions/aws-codebuild-run-build/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868766,"owners_count":21174758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-codebuild","codebuild","continuous-integration","devops","github-actions","serverless"],"created_at":"2024-11-10T08:29:54.730Z","updated_at":"2025-10-19T22:14:27.335Z","avatar_url":"https://github.com/aws-actions.png","language":"JavaScript","readme":"## AWS CodeBuild Run Build for GitHub Actions\n\nThis action runs a [AWS CodeBuild][codebuild] [project][codebuild project]\nas a step in a GitHub Actions workflow job.\n\nThe action builds the CodeBuild project, collects the build logs, and prints them as they are written.\nThe user experience is the same as it would be if the logic were executed\nin the GitHub Actions job runner.\n\n[Security issue notifications](./CONTRIBUTING.md#security-issue-notifications)\n\n**Related feature**: [Self-Hosted Runner in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/action-runner.html) allows GitHub Actions to integrate natively with AWS and access all compute platforms that CodeBuild offers, including Lambda, GPU-enhanced and Arm-based instances.\n\n## Usage\n\n### Inputs\n\nThis action offers following inputs that you can use to configure its behavior.\nThe only required input is `project-name`.\n\n1. **project-name** (required) : The name of CodeBuild project you want to run.\n1. **buildspec-override** (optional) :\n   The location (in this repository) of the [buildspec file][codebuild buildspec]\n   that CodeBuild requires.\n   By default, the action uses the buildspec file location\n   that you configured in the CodeBuild project.\n\n   Alternatively, you can pass in an inline buildspec definition like so:\n\n   ```\n   - name: Run CodeBuild\n     uses: aws-actions/aws-codebuild-run-build@v1\n     with:\n       project-name: my-codebuild-job\n       disable-source-override: true\n       buildspec-override:   |\n         version: 0.2\n         phases:\n           install:\n             runtime-versions:\n               nodejs: 16\n             commands:\n               - npm install -g typescript\n               - npm install\n           pre_build:\n             commands:\n               - echo Installing source NPM dependencies...\n           build:\n             commands:\n               - echo Build started on `date`\n               - tsc\n               - npm prune --production\n             post_build:\n               commands:\n                 - echo Build completed on `date`\n         artifacts:\n           type: zip\n           files:\n             - package.json\n             - package-lock.json\n   ```\n\n1. **compute-type-override** (optional) :\n   The name of a compute type for this build that overrides the one specified\n   in the build project.\n1. **environment-type-override** (optional) :\n   A container type for this build that overrides the one specified in the\n   build project.\n1. **image-override** (optional) :\n   The name of an image for this build that overrides the one specified\n   in the build project.\n1. **image-pull-credentials-type-override** (optional) :\n   The type of credentials CodeBuild uses to pull images in your build.\n1. **disable-source-override** (optional) :\n   Set to `true` if you want to disable providing `sourceVersion`,\n   `sourceTypeOverride` and `sourceLocationOverride` to CodeBuild.\n1. **source-version-override** (optional) :\n   The source version that overrides the `sourceVersion` provided to Codebuild.\n1. **source-type-override** (optional) :\n   The source type that overrides the `sourceTypeOverride` provided to Codebuild.\n1. **source-location-override** (optional) :\n    The source location that overrides the `sourceLocationOverride` provided to Codebuild.\n1. **env-vars-for-codebuild** (optional) :\n   A comma-separated list of the names of environment variables\n   that the action passes from GitHub Actions to CodeBuild.\n\n   The action passes these environment variables to CodeBuild\n   along with any environment variables that have a `github` prefix.\n\n   This list is often the same or a subset of the list of environment variables\n   that you define for GitHub actions in the `env` property.\n\n   Note: If you specify an environment variable\n   with the same name as one defined in your CodeBuild project,\n   the one defined here replaces the one in the CodeBuild project.\n   For a list of CodeBuild environment variables, see\n\n1. **update-interval** (optional) :\n   Update interval as seconds for how often the API is called to check on the status.\n\n   A higher value mitigates the chance of hitting API rate-limiting especially when\n   running many instances of this action in parallel, but also introduces a larger\n   potential time overhead (ranging from 0 to update interval) for the action to\n   fetch the build result and finish.\n\n   Lower value limits the potential time overhead worst case but it may hit the API\n   rate-limit more often, depending on the use-case.\n\n   The default value is 30.\n\n1. **update-back-off** (optional) :\n   Base back-off time in seconds for the update interval.\n\n   When API rate-limiting is hit the back-off time, augmented with jitter, will be\n   added to the next update interval.\n   E.g. with update interval of 30 and back-off time of 15, upon hitting the rate-limit\n   the next interval for the update call will be 30 + random*between(0, 15 * 2 \\*\\* 0))\n   seconds and if the rate-limit is hit again the next interval will be\n   30 + random*between(0, 15 * 2 \\*\\* 1) and so on.\n\n   The default value is 15.\n\n1. **hide-cloudwatch-logs** (optional) :\n   Set to `true` if you do not want CloudWatch Logs to be streamed to GitHub Action.\n\n1. **disable-github-env-vars** (optional) :\n   Set to `true` if you want do disable github environment variables in codebuild.\n\n1. **stop-on-signals** (optional) :\n   Comma-separated list of signals that will cause any started builds to be\n   stopped. The default value is `SIGINT`, which is what GitHub sends processes\n   when a workflow is cancelled. This means you can use concurrency settings or\n   other GitHub features that cause workflow cancellations without leaving\n   orphan builds running. Set to an empty string to disable.\n\n1. **artifacts-type-override** (optional) :\n   If required, you can override the default behavior of CodeBuild artifacts. This feature is particularly useful for triggering CodeBuild projects configured within CodePipeline. You can set the artifacts to `NO_ARTIFACTS` in such cases\n\n### Outputs\n\n1. **aws-build-id** : The CodeBuild build ID of the build that the action ran.\n\n## Purpose\n\nThis action is designed to give you the power of GitHub Actions\nwith options available in [AWS CodeBuild][codebuild] for more CPU and memory,\nand access to other resources.\n\nGitHub Actions provides a powerful system of event-based workflows,\nbut the hosted job runners cannot exceed the defined computing and memory limits,\nand might prevent you from accessing resources that you need for your project.\n\n[AWS CodeBuild][codebuild] is a fully managed continuous integration service\nthat can compile source code, run tests, and produce software packages that are ready to deploy.\nIt supports more environment options than standard GitHub Actions,\nincluding a selection of powerful computing environments with additional memory.\n\n### Resources and Architecture\n\n[GitHub Actions job runners][github actions job runners] have 2 x86_64 CPU cores and 7 GB RAM.\n\nThis is enough for the most common activities,\nbut some large or complex builds need more resources,\nand some builds need access to special CPU architectures or hardware.\n\n[CodeBuild compute types][codebuild compute types] offer options including:\n\n- up to 72 x86_64 vCPUs\n- up to 255 GB RAM\n- up to 8 ARM64 vCPUs\n- GPU hardware devices\n\n### Access\n\nYour workflow might require access to assets, configuration, or resources\nthat are impossible, difficult, or simply expensive\nto access from GitHub's hosted job runners\nbut are easy or cheap to access from CodeBuild.\n\n## Credentials and Permissions\n\nIn order for the action to run your CodeBuild project,\nyou need to provide AWS credentials.\nWe recommend using [aws-actions/configure-aws-credentials]\nto configure your credentials for a job.\n\n**NOTE:\nGitHub Secrets are not passed to the runner when a workflow is triggered from a forked repository.\nThis means that you cannot use this action directly in a workflow\nthat is triggered by pull requests from a fork.\nSee the [GitHub Secrets docs][github secrets access] for more information.**\n\nThe credentials that you provide need to have the following permissions:\n\n- `codebuild:StartBuild`\n- `codebuild:BatchGetBuilds`\n- `logs:GetLogEvents`\n\nFor example:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\"codebuild:StartBuild\", \"codebuild:BatchGetBuilds\"],\n      \"Resource\": [\"arn:aws:codebuild:REGION:ACCOUNT_ID:project/PROJECT_NAME\"]\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\"logs:GetLogEvents\"],\n      \"Resource\": [\n        \"arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/codebuild/PROJECT_NAME:*\"\n      ]\n    }\n  ]\n}\n```\n\n## Examples\n\nThese examples show how you can define a step in a workflow job.\nFor more information about GitHub Actions workflow syntax,\nsee the [GitHub docs][github workflow syntax].\n\nIf your CodeBuild project is already configured the way you want it,\nthe only CodeBuild Run input you need to provide is the project name.\n\n```yaml\n- name: Configure AWS Credentials\n  uses: aws-actions/configure-aws-credentials@v1\n  with:\n    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n    aws-region: us-east-2\n- name: Run CodeBuild\n  uses: aws-actions/aws-codebuild-run-build@v1\n  with:\n    project-name: CodeBuildProjectName\n```\n\nIf you reuse a project in multiple jobs or repositories,\nyou might want to provide a bit more configuration.\nFor example, the following configuration\nspecifies an alternate location for the buildspec file.\nIt also tells AWS CodeBuild Run Build\nto send all of the environment variables defined in the `env:` list to CodeBuild.\nIf any of these environment variables are defined in the CodeBuild project,\nthis will overwrite them.\n\n```yaml\n- name: Configure AWS Credentials\n  uses: aws-actions/configure-aws-credentials@v1\n  with:\n    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n    aws-region: us-east-2\n- name: Run CodeBuild\n  uses: aws-actions/aws-codebuild-run-build@v1\n  with:\n    project-name: CodeBuildProjectName\n    buildspec-override: path/to/buildspec.yaml or inline buildspec definition\n    compute-type-override: compute-type\n    environment-type-override: environment-type\n    image-override: ecr-image-uri\n    env-vars-for-codebuild: |\n      custom,\n      requester,\n      event-name\n  env:\n    custom: my environment variable\n    requester: ${{ github.actor }}\n    event-name: ${{ github.event_name }}\n```\n\n### Running Locally\n\nIt can be useful to run a build outside of CI.\nSo, this action can also be installed locally\nto kick off a CodeBuild project from your git sandbox.\nYou could push your changes to an open PR,\nbut if you only want to test one project this may be faster.\nIn order to use this tool,\nyou must first `git checkout` the commit that you want to test.\n\n```\nnpx @aws-actions/codebuild-run-build -p ProjectName -r remoteName\n```\n\nNote: If the above command returns a 404 error, you might need to add the package manually.\n```\nnpm install git@github.com:aws-actions/aws-codebuild-run-build.git\n# OR\nyard add git@github.com:aws-actions/aws-codebuild-run-build.git\n```\n\nThis will use whatever commit you have checked out\nand push to a temporary branch in the specified remote.\nThen kick off the build\nand delete the remote branch when complete.\n\nYou can also install the project globally or locally\nand execute it that way.\n\n## Implementation Notes\n\n### What we did\n\nWe call the [CodeBuild `StartBuild` API][codebuild startbuild],\nchecking out the commit that triggered the workflow.\n\nThe action waits for the build to complete while logging everything written to the build's\n[Amazon CloudWatch Logs][cloudwatch logs] [logstream][cloudwatch logs concepts].\nIf the `buildStatus` value in the StartBuild response is `SUCCEEDED`, the action succeeds.\nOtherwise, it fails.\n\nIn the call to StartBuild, we pass in all\n`GITHUB_` [environment variables][github environment variables] in the GitHub Actions environment,\nplus any environment variables that you specified in the `env-vars-for-codebuild` input value.\n\nBy default, regardless of the project configuration in CodeBuild or GitHub Actions,\nwe always pass the following parameters and values to CodeBuild in the StartBuild API call.\n\n| CodeBuild value          | GitHub value                           |\n| ------------------------ | -------------------------------------- |\n| `sourceVersion`          | The commit that triggered the workflow |\n| `sourceTypeOverride`     | The string `'GITHUB'`                  |\n| `sourceLocationOverride` | The `HTTPS` git url for `context.repo` |\n\nIf you want to disable sending the parameters `sourceVersion`, `sourceTypeOverride` and `sourceLocationOverride` you can use `disable-source-override` input.\n\n### What we did not do\n\nThis action intentionally does not let you specify every option\nin the [CodeBuild::StartBuild][codebuild startbuild] API.\n\nBecause all GitHub Actions input values are passed through environment variables,\nthey must be simple strings.\nThis makes it difficult to pass complex structures as inputs.\n\nAlso, providing an input for every parameter in the `StartBuild` API\nwould have made it much more difficult to use and maintain this tool.\nWe would have to add many more inputs or require string values,\nwhile hoping that all supported configurations\nconformed to the environment variable length limits.\n\nFor this reason, and to simplify what we expect to be the most common use-cases,\nwe chose to start with the simplest possible configuration.\nIf you find that these options don't meet your needs, please open an issue to let us know.\n\n## Release Process\n\nBy creating a new Release a workflow is triggered creating a new commit which only contains `dist` and the `action.yml`. The necessary tags, i.e. for the release v1.0.7, the tag v1.0.7 is created and the v1.0 and v1 tags are updated.\n\nFor the tagging and building the [build-and-tag](https://github.com/JasonEtco/build-and-tag-action) action by [Jason Etcovitch](https://github.com/JasonEtco) is used. It expects to have the main attribute and a build script to be set in the `package.json`. It then builds the code with the ncc compiler and creates the new tag/ updates existing tags for minor and major versions automatically.\n\n## License\n\nThis SDK is distributed under the\n[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),\nsee LICENSE and NOTICE for more information.\n\n[codebuild]: https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html\n[codebuild project]: https://docs.aws.amazon.com/codebuild/latest/userguide/working-with-build-projects.html\n[codebuild startbuild]: https://docs.aws.amazon.com/codebuild/latest/APIReference/API_StartBuild.html\n[codebuild compute types]: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html\n[codebuild buildspec]: https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html\n[cloudwatch logs]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html\n[cloudwatch logs concepts]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogsConcepts.html\n[github environment variables]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables\n[github actions job runners]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#supported-runners-and-hardware-resources\n[github workflow syntax]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions\n[github secrets access]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#using-encrypted-secrets-in-a-workflow\n[aws-actions/configure-aws-credentials]: https://github.com/aws-actions/configure-aws-credentials\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-actions%2Faws-codebuild-run-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-actions%2Faws-codebuild-run-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-actions%2Faws-codebuild-run-build/lists"}