Skip to content

Commit f971265

Browse files
committed
Change name to 'General Docker Build Pipeline Action' and update README.md
1 parent 3f49187 commit f971265

File tree

3 files changed

+4
-264
lines changed

3 files changed

+4
-264
lines changed

README.md

Lines changed: 3 additions & 256 deletions
Original file line numberDiff line numberDiff line change
@@ -1,258 +1,5 @@
1-
## AWS CodeBuild Run Build for GitHub Actions
1+
# General docker build pipeline action
22

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.
54

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.

action.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: 'GDBP: Start AWS CodeBuild Project via Lambda Function'
1+
name: 'General Docker Build Pipeline Action'
22
description: 'Invokes an AWS Lambda function that starts and returns the ID of an AWS CodeBuild project and streams the build logs back to Github.'
33
inputs:
44
env-vars-for-codebuild:

dist/index.js

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -59733,17 +59733,10 @@ async function build(sdk, params) {
5973359733
sourceVersion: params.sourceVersion
5973459734
})
5973559735
}
59736-
console.log("Invoking lambda function.")
5973759736
const response = await sdk.lambda.invoke(lambdaParams).promise();
59738-
console.log("Invoked lambda function.")
59739-
console.log("Response is")
59740-
console.log(response)
5974159737
const start = JSON.parse(JSON.parse(response.Payload))
59742-
console.log("Start is:")
59743-
console.log(start)
5974459738

5974559739
// Wait for the build to "complete"
59746-
5974759740
return waitForBuildEndTime(sdk, start.build);
5974859741
}
5974959742

0 commit comments

Comments
 (0)