Skip to content

Commit bd1cdc1

Browse files
jordanstephensjordanstephens
committed
document github actions deployment to aws
1 parent 962b3e1 commit bd1cdc1

File tree

4 files changed

+196
-84
lines changed

4 files changed

+196
-84
lines changed

‎docs/tutorials/deploying-from-github-actions.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Deploying from GitHub Actions
3+
description: Using the Defang Github Action to deploy your project from your CI/CD pipeline.
4+
---
5+
6+
# Deploying from GitHub Actions
7+
8+
Defang makes it easy to deploy your applications directly from your GitHub Actions workflow using the [Defang GitHub Action](https://github.com/DefangLabs/defang-github-action).
9+
10+
There is a dedicated tutorial for deploying to each cloud provider:
11+
* [AWS](/docs/tutorials/deploying-from-github-actions/to-aws)
12+
* [GCP](/docs/tutorials/deploying-from-github-actions/to-gcp).

‎docs/tutorials/deploying-from-github-actions/to-aws.mdx‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Deploying to AWS from GitHub Actions
3+
description: Using the Defang Github Action to deploy your project to AWS from your CI/CD pipeline.
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
9+
# Deploying to AWS from GitHub Actions
10+
11+
This tutorial will show you how to use the [Defang GitHub Action](https://github.com/DefangLabs/defang-github-action) to deploy your project to AWS from your GitHub Actions workflow.
12+
13+
## Prerequisites
14+
15+
- [A Defang Account](/docs/concepts/authentication)
16+
- [A Github Repo](https://docs.github.com/en/get-started/quickstart/create-a-repo)
17+
- [An AWS Account](https://aws.amazon.com)
18+
19+
The following steps will guide you through setting up a GitHub Actions workflow that can assume a role in your AWS account using OpenID Connect (OIDC) and deploy your project using the Defang GitHub Action. The role which will be assumed must have a trust relationship with an OIDC identity provider (IdP) for GitHub Actions, and that trust relationship must be configured to allow the specific repository and branch to assume the role. This ultimately allows the GitHub Actions workflow to securely access your AWS resources without needing to store long-lived AWS credentials in your repository.
20+
21+
## Step 1 - Identify your AWS Account ID
22+
23+
To configure the GitHub Action to assume a role in your AWS account, you'll need your AWS Account ID.
24+
25+
<Tabs>
26+
<TabItem value="cli" label="AWS CLI" default>
27+
```bash
28+
aws sts get-caller-identity --query Account --output text
29+
123456789012 # for example
30+
```
31+
</TabItem>
32+
<TabItem value="dashboard" label="AWS Dashboard">
33+
1. Go to the [AWS Management Console](https://aws.amazon.com/console/).
34+
2. In the top right corner, click on your account name or number.
35+
3. Your AWS Account ID will be displayed in the dropdown menu.
36+
</TabItem>
37+
</Tabs>
38+
39+
## Step 2 - Create an AWS Identity Provider for GitHub Actions
40+
41+
You will need to create a new OIDC Identity Provider in AWS to enable GitHub Actions to assume roles in your AWS account.
42+
43+
<Tabs>
44+
<TabItem value="cli" label="AWS CLI" default>
45+
Using the AWS CLI:
46+
47+
```
48+
aws iam create-open-id-connect-provider --client-id-list sts.amazonaws.com --url https://token.actions.githubusercontent.com
49+
```
50+
</TabItem>
51+
<TabItem value="dashboard" label="AWS Dashboard">
52+
Using the AWS Dashboard:
53+
54+
1. Go to the [AWS IAM Console](https://console.aws.amazon.com/iam/home#/roles).
55+
2. Click on "Identity providers" in the left sidebar.
56+
3. Click on "Add provider".
57+
4. Choose "OIDC" as the provider type.
58+
5. For the provider URL, enter `https://token.actions.githubusercontent.com`.
59+
6. For the audience, enter `sts.amazonaws.com`.
60+
7. Click "Add provider".
61+
</TabItem>
62+
</Tabs>
63+
64+
## Step 3 - Create a deployer role with trust relationship for GitHub Actions
65+
66+
<Tabs>
67+
<TabItem value="cli" label="AWS CLI" default>
68+
Using the AWS CLI:
69+
70+
1. Create a trust policy document
71+
72+
```bash
73+
cat > deployer-policy.json << EOF
74+
{
75+
"Version": "2012-10-17",
76+
"Statement": [
77+
{
78+
"Effect": "Allow",
79+
"Action": "*",
80+
"Resource": "*"
81+
},
82+
{
83+
"Sid": "OidcForGitHub",
84+
"Effect": "Allow",
85+
"Principal": {
86+
"Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
87+
},
88+
"Action": "sts:AssumeRoleWithWebIdentity",
89+
"Condition": {
90+
"StringLike": {
91+
"token.actions.githubusercontent.com:sub": "repo:YOUR_REPO_OWNER/YOUR_REPO_NAME:ref:refs/heads/YOUR_BRANCH_NAME"
92+
},
93+
"StringEquals": {
94+
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
95+
}
96+
}
97+
}
98+
]
99+
}
100+
EOF
101+
```
102+
103+
2. Edit the `deployer-policy.json` file to replace the following placeholders:
104+
* `YOUR_AWS_ACCOUNT_ID` replace this with your actual AWS Account ID
105+
* `YOUR_REPO_OWNER` your GitHub username or organization name (e.g., `ACMELabs`)
106+
* `YOUR_REPO_NAME` your GitHub repository name (e.g., `my-project`)
107+
* `YOUR_BRANCH_NAME` the branch you want to deploy from (e.g., `main`). If you want to allow multiple branches, you can use a wildcard like `*`
108+
109+
3. Create a deployer role
110+
```
111+
aws iam create-role --role-name deployer --assume-role-policy-document file://deployer-policy.json
112+
```
113+
114+
</TabItem>
115+
<TabItem value="dashboard" label="AWS Dashboard">
116+
Using the AWS Dashboard:
117+
118+
1. Navigate to [AWS IAM Console](https://console.aws.amazon.com/iam/home#/roles).
119+
2. Click on "Create role".
120+
3. Select "Web identity" as the trusted entity type.
121+
4. For the identity provider, select the OIDC provider you created in the previous step.
122+
5. For the audience, enter `sts.amazonaws.com`.
123+
6. For the GitHub organization, enter your GitHub username or organization name (e.g., `ACMELabs`).
124+
7. For the GitHub repository, enter your GitHub repository name (e.g., `my-project`).
125+
8. For the GitHub branch, enter the branch you want to deploy from (e.g., `main`). If you want to allow multiple branches, you can use a wildcard like `*`.
126+
9. Click "Next".
127+
10. Select the `AdministratorAccess` policy to attach to the role.
128+
11. Click "Next".
129+
12. For the role name, enter `deployer`.
130+
13. For the role description, enter "This role is assumed by GitHub Actions when deploying with Defang".
131+
13. Click "Create role".
132+
133+
</TabItem>
134+
</Tabs>
135+
136+
## Step 4 - Create a new GitHub Actions workflow
137+
138+
In your GitHub repository, create a new file at `.github/workflows/deploy.yml` with the following content:
139+
140+
```yaml
141+
name: Deploy with Defang
142+
on:
143+
push:
144+
branches:
145+
- main # Change this to your default branch if it's not 'main', this must match the branch you specified in the deployer role's trust relationship.
146+
jobs:
147+
deploy:
148+
runs-on: ubuntu-latest
149+
permissions:
150+
contents: read
151+
id-token: write
152+
153+
steps:
154+
- name: Configure AWS Credentials for CI
155+
uses: aws-actions/configure-aws-credentials@v4
156+
with:
157+
aws-region: us-west-2
158+
# Replace with your AWS Account ID and the name of the role which we previously created.
159+
role-to-assume: arn:aws:iam::123456789012:role/deployer
160+
161+
- name: Checkout Repo
162+
uses: actions/checkout@v4
163+
164+
- name: Deploy
165+
uses: DefangLabs/[email protected]
166+
with:
167+
provider: "aws"
168+
```
169+
170+
:::info
171+
Full documentation for configuring AWS can be found in the [Defang GitHub Action repository](https://github.com/DefangLabs/defang-github-action).
172+
:::
173+
174+
Now you have configured a GitHub Actions workflow that uses the Defang GitHub Action to deploy your project to AWS securely using OIDC and short-lived credentials. Whenever you push to the specified branch, the workflow will run and deploy your project using the permissions granted to the `deployer` role in your AWS account.

‎docs/tutorials/deploying-from-github-actions/to-gcp.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Deploying to GCP from GitHub Actions
3+
description: Using the Defang Github Action to deploy your project to GCP from your CI/CD pipeline.
4+
---
5+
6+
# Deploying to GCP from GitHub Actions
7+
8+
:::info
9+
Coming soon
10+
:::

‎docs/tutorials/github-actions.md‎

Lines changed: 0 additions & 84 deletions
This file was deleted.

0 commit comments

Comments
 (0)