You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/dark-mechanicum/aws-codebuild/actions/workflows/codeql.yml)
4
-
[](https://github.com/dark-mechanicum/aws-codebuild/actions/workflows/validation.yml)
Simple, but very powerful GitHub Action to trigger AWS CodeBuild jobs with overrides all parameters and job execution log output.
7
9
@@ -27,13 +29,14 @@ jobs:
27
29
28
30
## Description
29
31
30
-
Under the hood it's using JavaScript AWS SDK for making calls to the AWS API. It means, you can put [any parameters](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html#startBuild-property) for triggering your AWS CodeBuild Job.
32
+
Under the hood it's using AWS SDK for JavaScript (v3) for making calls to the AWS API. It means, you can put [any parameters](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/codebuild/command/StartBuildCommand/) for triggering your AWS CodeBuild Job.
31
33
32
34
In case if AWS CodeBuild job execution will be failed, it also will fail execution of GitHub Action.
33
35
34
36
In case if you have enabled AWS CloudWatch logs for AWS CodeBuild job execution, it will put AWS CloudWatch logs output in the GitHub Actions logs output.
35
37
36
38
## Inputs
39
+
37
40
```yaml
38
41
- name: Executing AWS CodeBuild task
39
42
uses: dark-mechanicum/aws-codebuild@v1
@@ -56,28 +59,32 @@ In case if you have enabled AWS CloudWatch logs for AWS CodeBuild job execution,
56
59
}'
57
60
```
58
61
59
-
*`projectName` [string] [required] - The name of the CodeBuild build project to start running a build
60
-
* `buildStatusInterval` [number] [optional] - Interval in milliseconds to control how often should be checked status of build
61
-
* `logsUpdateInterval` [number] [optional] - Interval in milliseconds to control how often should be checked new events in logs stream
62
-
* `waitToBuildEnd` [boolean] [optional] - Wait till AWS CodeBuild job will be finished
63
-
* `displayBuildLogs` [boolean] [optional] - Display AWS CodeBuild logs output in the GitHub Actions logs output
64
-
* `redirectServiceURL` [string] [optional] - In case if that option will be enabled, in the Summary Report, all links will be replaced by the pattern `${redirectServiceURL}${base64_encoded/link}`. That can be useful when some other actions masking credentials like AWS Account ID, Region etc. It will make default generated urls unusable. You can use `https://cloudaws.link/r/` value like example of service usage
65
-
* `buildspec` [string] [optional] - Custom parameters to override job parameters in the valid JSON format. Full list of supported parameters you can find in the [CodeBuild.startBuild()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html#startBuild-property) documentation
62
+
-`projectName` [string] [required] - The name of the CodeBuild build project to start running a build
63
+
-`buildStatusInterval`[number] [optional] - Interval in milliseconds to control how often should be checked status of build
64
+
-`logsUpdateInterval`[number] [optional] - Interval in milliseconds to control how often should be checked new events in logs stream
65
+
-`waitToBuildEnd`[boolean] [optional] - Wait till AWS CodeBuild job will be finished
66
+
-`displayBuildLogs`[boolean] [optional] - Display AWS CodeBuild logs output in the GitHub Actions logs output
67
+
-`redirectServiceURL`[string] [optional] - In case if that option will be enabled, in the Summary Report, all links will be replaced by the pattern `${redirectServiceURL}${base64_encoded/link}`. That can be useful when some other actions masking credentials like AWS Account ID, Region etc. It will make default generated urls unusable. You can use `https://cloudaws.link/r/` value like example of service usage
68
+
-`buildspec`[string] [optional] - Custom parameters to override job parameters in the valid JSON format. Full list of supported parameters you can find in the [StartBuildCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/codebuild/command/StartBuildCommand/) documentation
66
69
67
70
## AWS Credentials
68
71
69
72
You can use 2 ways how to put AWS access credentials to this action:
70
73
71
74
### Environment Variables
75
+
72
76
[Using environment variables](https://docs.github.com/en/actions/learn-github-actions/environment-variables) (globally or locally):
- **AWS_REGION** - AWS Region where is deployed a CodeBuild Project
76
81
77
82
### Using aws-actions/configure-aws-credentials GitHub Action
83
+
78
84
Setting up credentials files ([AWS Documentation](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html)). Simplest way to do it - use [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) GitHub Action.
79
85
80
86
Important: if you want a links working correctly in Summary report, remember that action will mask by `***` region, account number and other credentials. If you want make links working, you should assign redirect service to the `redirectServiceURL` action input.
87
+
81
88
```yaml
82
89
- name: Configure AWS Credentials
83
90
uses: aws-actions/configure-aws-credentials@v1
@@ -93,9 +100,10 @@ Important: if you want a links working correctly in Summary report, remember tha
93
100
```
94
101
95
102
## Configuration
103
+
96
104
Unfortunately, [GitHub Actions syntax](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions) do not support complex data types. I've made a decision to use environment variables for building configuration object overrides. It means, you can extend configuration for your AWS CodeBuild Job request with using of environment variables.
97
105
98
-
Most elegant way to implement overriding of [CodeBuild.startBuild()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html#startBuild-property) is using `buildspec` input. The `buildspec` input should contain valid JSON object with values that you are planning to override.
106
+
Most elegant way to implement overriding of [StartBuildCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/codebuild/command/StartBuildCommand/) is using `buildspec` input. The `buildspec` input should contain valid JSON object with values that you are planning to override.
99
107
100
108
```yaml
101
109
- name: Executing AWS CodeBuild task
@@ -105,7 +113,7 @@ Most elegant way to implement overriding of [CodeBuild.startBuild()](https://doc
@@ -119,7 +127,7 @@ Most elegant way to implement overriding of [CodeBuild.startBuild()](https://doc
119
127
120
128
For overriding through environment variables, you need to define environment variable `CODEBUILD__environmentVariablesOverride` and assign complex and valid JSON value to that variable.
121
129
122
-
To example, if you want to override `environmentVariablesOverride` property (it requires array of objects), you need define `CODEBUILD__environmentVariablesOverride` and assign to it required JSON value
130
+
To example, if you want to override `environmentVariablesOverride` property (it requires array of objects), you need define `CODEBUILD__environmentVariablesOverride` and assign to it required JSON value
123
131
124
132
```yaml
125
133
- name: AWS CodeBuild Job
@@ -133,7 +141,8 @@ To example, if you want to override `environmentVariablesOverride` property (it
133
141
]'
134
142
```
135
143
136
-
In case, if configuration option do not have a complex type, you can define single environment variable with required to you value.
144
+
In case, if configuration option do not have a complex type, you can define single environment variable with required to you value.
Current action provides a set of outputs, that you can use in the next steps:
188
195
189
-
* `id` [string] - The unique ID for the build
190
-
* `success` [boolean] - Flag that marks is current AWS CodeBuild job was finished successfully
191
-
* `buildNumber` [number] - The number of the build. For each project, the buildNumber of its first build is 1. The buildNumber of each subsequent build is incremented by 1. If a build is deleted, the buildNumber of other builds does not change.
192
-
* `timeoutInMinutes` [number] - How long, in minutes, from 5 to 480 (8 hours), for CodeBuild to wait before timing out any related build that did not get marked as completed. The default is 60 minutes
193
-
* `initiator` [string] - The AWS entity that started the build
194
-
* `buildStatus` [string] - The final status of the build. Valid values include:
195
-
* `FAILED`: The build failed.
196
-
* `FAULT`: The build faulted.
197
-
* `IN_PROGRESS`: The build is still in progress.
198
-
* `STOPPED`: The build stopped.
199
-
* `SUCCEEDED`: The build succeeded.
200
-
* `TIMED_OUT`: The build timed out.
196
+
- `id`[string] - The unique ID for the build
197
+
- `success`[boolean] - Flag that marks is current AWS CodeBuild job was finished successfully
198
+
- `buildNumber`[number] - The number of the build. For each project, the buildNumber of its first build is 1. The buildNumber of each subsequent build is incremented by 1. If a build is deleted, the buildNumber of other builds does not change.
199
+
- `timeoutInMinutes`[number] - How long, in minutes, from 5 to 480 (8 hours), for CodeBuild to wait before timing out any related build that did not get marked as completed. The default is 60 minutes
200
+
- `initiator`[string] - The AWS entity that started the build
201
+
- `buildStatus` [string] - The final status of the build. Valid values include:
202
+
- `FAILED`: The build failed.
203
+
- `FAULT`: The build faulted.
204
+
- `IN_PROGRESS`: The build is still in progress.
205
+
- `STOPPED`: The build stopped.
206
+
- `SUCCEEDED`: The build succeeded.
207
+
- `TIMED_OUT`: The build timed out.
208
+
209
+
## GitHub Actions Summary
210
+
211
+
This action automatically generates a detailed [job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary) that appears in the GitHub Actions UI. The summary includes:
212
+
213
+
- **Build Information**: Job ID, project name, initiator, and execution time
214
+
- **AWS Console Link**: Direct link to the CodeBuild job in AWS Console
215
+
- **CloudWatch Logs Link**: Link to view logs in AWS CloudWatch (when logs are enabled)
216
+
- **Build Configuration**: The buildspec parameters used to start the job
217
+
- **Build Phases Table**: Detailed breakdown of each build phase with status and duration
218
+
219
+
The summary is automatically generated when the build completes and provides a comprehensive overview of the CodeBuild execution without requiring manual log parsing.
220
+
221
+
### Link Redirection Service
222
+
223
+
When using the `redirectServiceURL` parameter, all AWS console and CloudWatch links in the summary will be encoded through the redirect service. This is useful when other GitHub Actions mask AWS credentials (account ID, region) making direct links unusable.
224
+
225
+
Example redirect URL: `https://cloudaws.link/r/`
226
+
227
+
## Requirements
228
+
229
+
- **Node.js**: 20 or higher
230
+
- **GitHub Actions**: Compatible with all GitHub Actions environments
231
+
- **AWS SDK**: Uses AWS SDK for JavaScript v3
232
+
233
+
## Troubleshooting
234
+
235
+
### Common Issues
236
+
237
+
**CodeBuild job fails to start**
238
+
239
+
- Verify that the `projectName` matches exactly with your AWS CodeBuild project name
240
+
- Check that your AWS credentials have `codebuild:StartBuild` permission
241
+
- Ensure the CodeBuild project exists in the specified AWS region
242
+
243
+
**Logs not displaying**
244
+
245
+
- Verify CloudWatch logs are enabled in your CodeBuild project settings
246
+
- Check that your AWS credentials have `logs:GetLogEvents` permission
247
+
- Ensure the `displayBuildLogs` input is set to `true` (default)
248
+
249
+
**Links in summary not working**
250
+
251
+
- AWS console links may be masked by `aws-actions/configure-aws-credentials`
252
+
- Use the `redirectServiceURL` parameter to enable working links
0 commit comments