|
1 | | -## AWS CodeBuild Run Build for GitHub Actions |
| 1 | +# General docker build pipeline action |
2 | 2 |
|
3 | | -This action runs a [AWS CodeBuild][codebuild] [project][codebuild project] |
4 | | -as a step in a GitHub Actions workflow job. |
| 3 | +A github action that works in coordination with a [general docker build pipeline](https://github.com/brave-intl/general-docker-build-pipeline) to kick off a Lambda function that starts a build. |
5 | 4 |
|
6 | | -The action builds the CodeBuild project, collects the build logs, and prints them as they are written. |
7 | | -The user experience is the same as it would be if the logic were executed |
8 | | -in the GitHub Actions job runner. |
9 | | - |
10 | | -[Security issue notifications](./CONTRIBUTING.md#security-issue-notifications) |
11 | | - |
12 | | -## Usage |
13 | | - |
14 | | -### Inputs |
15 | | - |
16 | | -This action offers three inputs that you can use to configure its behavior. |
17 | | -The only required input is `project-name`. |
18 | | - |
19 | | -1. **project-name** (required) : The name of CodeBuild project you want to run. |
20 | | -1. **buildspec-override** (optional) : |
21 | | - The location (in this repository) of the [buildspec file][codebuild buildspec] |
22 | | - that CodeBuild requires. |
23 | | - By default, the action uses the buildspec file location |
24 | | - that you configured in the CodeBuild project. |
25 | | -1. **env-vars-for-codebuild** (optional) : |
26 | | - A comma-separated list of the names of environment variables |
27 | | - that the action passes from GitHub Actions to CodeBuild. |
28 | | - |
29 | | - The action passes these environment variables to CodeBuild |
30 | | - along with any environment variables that have a `github` prefix. |
31 | | - |
32 | | - This list is often the same or a subset of the list of environment variables |
33 | | - that you define for GitHub actions in the `env` property. |
34 | | - |
35 | | - Note: If you specify an environment variable |
36 | | - with the same name as one defined in your CodeBuild project, |
37 | | - the one defined here replaces the one in the CodeBuild project. |
38 | | - For a list of CodeBuild environment variables, see |
39 | | - |
40 | | -### Outputs |
41 | | - |
42 | | -1. **aws-build-id** : The CodeBuild build ID of the build that the action ran. |
43 | | - |
44 | | -## Purpose |
45 | | - |
46 | | -This action is designed to give you the power of GitHub Actions |
47 | | -with options available in [AWS CodeBuild][codebuild] for more CPU and memory, |
48 | | -and access to other resources. |
49 | | - |
50 | | -GitHub Actions provides a powerful system of event-based workflows, |
51 | | -but the hosted job runners cannot exceed the defined computing and memory limits, |
52 | | -and might prevent you from accessing resources that you need for your project. |
53 | | - |
54 | | -[AWS CodeBuild][codebuild] is a fully managed continuous integration service |
55 | | -that can compile source code, run tests, and produce software packages that are ready to deploy. |
56 | | -It supports more environment options than standard GitHub Actions, |
57 | | -including a selection of powerful computing environments with additional memory. |
58 | | - |
59 | | -### Resources and Architecture |
60 | | - |
61 | | -[GitHub Actions job runners][github actions job runners] have 2 x86_64 CPU cores and 7 GB RAM. |
62 | | - |
63 | | -This is enough for the most common activities, |
64 | | -but some large or complex builds need more resources, |
65 | | -and some builds need access to special CPU architectures or hardware. |
66 | | - |
67 | | -[CodeBuild compute types][codebuild compute types] offer options including: |
68 | | - |
69 | | -- up to 72 x86_64 vCPUs |
70 | | -- up to 255 GB RAM |
71 | | -- up to 8 ARM64 vCPUs |
72 | | -- GPU hardware devices |
73 | | - |
74 | | -### Access |
75 | | - |
76 | | -Your workflow might require access to assets, configuration, or resources |
77 | | -that are impossible, difficult, or simply expensive |
78 | | -to access from GitHub's hosted job runners |
79 | | -but are easy or cheap to access from CodeBuild. |
80 | | - |
81 | | -## Credentials and Permissions |
82 | | - |
83 | | -In order for the action to run your CodeBuild project, |
84 | | -you need to provide AWS credentials. |
85 | | -We recommend using [aws-actions/configure-aws-credentials] |
86 | | -to configure your credentials for a job. |
87 | | - |
88 | | -**NOTE: |
89 | | -GitHub Secrets are not passed to the runner when a workflow is triggered from a forked repository. |
90 | | -This means that you cannot use this action directly in a workflow |
91 | | -that is triggered by pull requests from a fork. |
92 | | -See the [GitHub Secrets docs][github secrets access] for more information.** |
93 | | - |
94 | | -The credentials that you provide need to have the following permissions: |
95 | | - |
96 | | -- `codebuild:StartBuild` |
97 | | -- `codebuild:BatchGetBuilds` |
98 | | -- `logs:GetLogEvents` |
99 | | - |
100 | | -For example: |
101 | | - |
102 | | -```json |
103 | | -{ |
104 | | - "Version": "2012-10-17", |
105 | | - "Statement": [ |
106 | | - { |
107 | | - "Effect": "Allow", |
108 | | - "Action": ["codebuild:StartBuild", "codebuild:BatchGetBuilds"], |
109 | | - "Resource": ["arn:aws:codebuild:REGION:ACCOUNT_ID:project/PROJECT_NAME"] |
110 | | - }, |
111 | | - { |
112 | | - "Effect": "Allow", |
113 | | - "Action": ["logs:GetLogEvents"], |
114 | | - "Resource": [ |
115 | | - "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/codebuild/PROJECT_NAME:*" |
116 | | - ] |
117 | | - } |
118 | | - ] |
119 | | -} |
120 | | -``` |
121 | | - |
122 | | -## Examples |
123 | | - |
124 | | -These examples show how you can define a step in a workflow job. |
125 | | -For more information about GitHub Actions workflow syntax, |
126 | | -see the [GitHub docs][github workflow syntax]. |
127 | | - |
128 | | -If your CodeBuild project is already configured the way you want it, |
129 | | -the only CodeBuild Run input you need to provide is the project name. |
130 | | - |
131 | | -```yaml |
132 | | -- name: Configure AWS Credentials |
133 | | - uses: aws-actions/configure-aws-credentials@v1 |
134 | | - with: |
135 | | - aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} |
136 | | - aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} |
137 | | - aws-region: us-east-2 |
138 | | -- name: Run CodeBuild |
139 | | - uses: aws-actions/[email protected] |
140 | | - with: |
141 | | - project-name: CodeBuildProjectName |
142 | | -``` |
143 | | -
|
144 | | -If you reuse a project in multiple jobs or repositories, |
145 | | -you might want to provide a bit more configuration. |
146 | | -For example, the following configuration |
147 | | -specifies an alternate location for the buildspec file. |
148 | | -It also tells AWS CodeBuild Run Build |
149 | | -to send all of the environment variables defined in the `env:` list to CodeBuild. |
150 | | -If any of these environment variables are defined in the CodeBuild project, |
151 | | -this will overwrite them. |
152 | | - |
153 | | -```yaml |
154 | | -- name: Configure AWS Credentials |
155 | | - uses: aws-actions/configure-aws-credentials@v1 |
156 | | - with: |
157 | | - aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} |
158 | | - aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} |
159 | | - aws-region: us-east-2 |
160 | | -- name: Run CodeBuild |
161 | | - uses: aws-actions/[email protected] |
162 | | - with: |
163 | | - project-name: CodeBuildProjectName |
164 | | - buildspec-override: path/to/buildspec.yaml |
165 | | - env-vars-for-codebuild: | |
166 | | - custom, |
167 | | - requester, |
168 | | - event-name |
169 | | - env: |
170 | | - custom: my environment variable |
171 | | - requester: ${{ github.actor }} |
172 | | - event-name: ${{ github.event_name }} |
173 | | -``` |
174 | | - |
175 | | -### Running Locally |
176 | | - |
177 | | -It can be useful to run a build outside of CI. |
178 | | -So, this action can also be installed locally |
179 | | -to kick off a CodeBuild project from your git sandbox. |
180 | | -You could push your changes to an open PR, |
181 | | -but if you only want to test one project this may be faster. |
182 | | -In order to use this tool, |
183 | | -you must first `git checkout` the commit that you want to test. |
184 | | - |
185 | | -``` |
186 | | -npx @aws-actions/codebuild-run-build -p ProjectName -r remoteName |
187 | | -``` |
188 | | -
|
189 | | -This will use whatever commit you have checked out |
190 | | -and push to a temporary branch in the specified remote. |
191 | | -Then kick off the build |
192 | | -and delete the remote branch when complete. |
193 | | -
|
194 | | -You can also install the project globally or locally |
195 | | -and execute it that way. |
196 | | -
|
197 | | -## Implementation Notes |
198 | | -
|
199 | | -### What we did |
200 | | -
|
201 | | -We call the [CodeBuild `StartBuild` API][codebuild startbuild], |
202 | | -checking out the commit that triggered the workflow. |
203 | | -
|
204 | | -The action waits for the build to complete while logging everything written to the build's |
205 | | -[Amazon CloudWatch Logs][cloudwatch logs] [logstream][cloudwatch logs concepts]. |
206 | | -If the `buildStatus` value in the StartBuild response is `SUCCEEDED`, the action succeeds. |
207 | | -Otherwise, it fails. |
208 | | -
|
209 | | -In the call to StartBuild, we pass in all |
210 | | -`GITHUB_` [environment variables][github environment variables] in the GitHub Actions environment, |
211 | | -plus any environment variables that you specified in the `evn-passthrough` input value. |
212 | | -
|
213 | | -Regardless of the project configuration in CodeBuild or GitHub Actions, |
214 | | -we always pass the following parameters and values to CodeBuild in the StartBuild API call. |
215 | | -
|
216 | | -| CodeBuild value | GitHub value | |
217 | | -| ------------------------ | -------------------------------------- | |
218 | | -| `sourceVersion` | The commit that triggered the workflow | |
219 | | -| `sourceTypeOverride` | The string `'GITHUB'` | |
220 | | -| `sourceLocationOverride` | The `HTTPS` git url for `context.repo` | |
221 | | -
|
222 | | -### What we did not do |
223 | | -
|
224 | | -This action intentionally does not let you specify every option |
225 | | -in the [CodeBuild::StartBuild][codebuild startbuild] API. |
226 | | -
|
227 | | -Because all GitHub Actions input values are passed through environment variables, |
228 | | -they must be simple strings. |
229 | | -This makes it difficult to pass complex structures as inputs. |
230 | | -
|
231 | | -Also, providing an input for every parameter in the `StartBuild` API |
232 | | -would have made it much more difficult to use and maintain this tool. |
233 | | -We would have to add many more inputs or require string values, |
234 | | -while hoping that all supported configurations |
235 | | -conformed to the environment variable length limits. |
236 | | -
|
237 | | -For this reason, and to simplify what we expect to be the most common use-cases, |
238 | | -we chose to start with the simplest possible configuration. |
239 | | -If you find that these options don't meet your needs, please open an issue to let us know. |
240 | | -
|
241 | | -## License |
242 | | -
|
243 | | -This SDK is distributed under the |
244 | | -[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), |
245 | | -see LICENSE and NOTICE for more information. |
246 | | -
|
247 | | -[codebuild]: https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html |
248 | | -[codebuild project]: https://docs.aws.amazon.com/codebuild/latest/userguide/working-with-build-projects.html |
249 | | -[codebuild startbuild]: https://docs.aws.amazon.com/codebuild/latest/APIReference/API_StartBuild.html |
250 | | -[codebuild compute types]: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html |
251 | | -[codebuild buildspec]: https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html |
252 | | -[cloudwatch logs]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html |
253 | | -[cloudwatch logs concepts]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogsConcepts.html |
254 | | -[github environment variables]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables |
255 | | -[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 |
256 | | -[github workflow syntax]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions |
257 | | -[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 |
258 | | -[aws-actions/configure-aws-credentials]: https://github.com/aws-actions/configure-aws-credentials |
| 5 | +Run `npm run package` to create a new build. |
0 commit comments