From 9115c64d85604092e02863a352759dd787541c15 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Mon, 29 Sep 2025 16:59:47 -0700 Subject: [PATCH 1/3] github actions tutorial --- docs/tutorials/github-actions.md | 84 ++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/tutorials/github-actions.md diff --git a/docs/tutorials/github-actions.md b/docs/tutorials/github-actions.md new file mode 100644 index 000000000..15d2d59f2 --- /dev/null +++ b/docs/tutorials/github-actions.md @@ -0,0 +1,84 @@ +--- +title: Deploying from GitHub Actions +description: Using the Defang Github Action to deploy your project from your CI/CD pipeline. +--- + +# Deploying from GitHub Actions + +This tutorial will show you how to use the [Defang GitHub Action](https://github.com/DefangLabs/defang-github-action) to deploy your project from your GitHub Actions workflow. + +## Prerequisites + +- [A Defang Account](/docs/concepts/authentication) +- [A Github Repo](https://docs.github.com/en/get-started/quickstart/create-a-repo) + +## Step 1 - Create a new GitHub Actions workflow + +### AWS + +In your GitHub repository, create a new file at `.github/workflows/deploy.yml` with the following content: + +```yaml +name: Deploy to Defang +on: + push: + branches: + - main # Change this to your default branch if it's not 'main' +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + + steps: + - name: Configure AWS Credentials for CI + uses: aws-actions/configure-aws-credentials@v4 + with: + aws-region: us-west-2 + role-to-assume: arn:aws:iam::123456789012:role/ci-role + + - name: Checkout Repo + uses: actions/checkout@v4 + + - name: Deploy + uses: DefangLabs/defang-github-action@v1.2.1 + with: + mode: "balanced" + provider: "aws" +``` + +### GCP + +```yaml +name: Deploy to Defang +on: + push: + branches: + - main # Change this to your default branch if it's not 'main' +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + + steps: + - name: Configure GCP Credentials for Prod + uses: "google-github-actions/auth@v2" + with: + workload_identity_provider: "projects/123456789012/locations/global/workloadIdentityPools/github-actions-pool/providers/my-project-repo-provider" + + - name: Checkout Repo + uses: actions/checkout@v4 + + - name: Deploy + uses: DefangLabs/defang-github-action@v1.2.1 + with: + mode: "balanced" + provider: "gcp" +``` + +Full documentation for configuring AWS and GCP credentials can be found in the [Defang GitHub Action repository](https://github.com/DefangLabs/defang-github-action). + + From 962b3e14bab73d8701e80203a60e9529a6019f6c Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 1 Oct 2025 17:42:56 -0700 Subject: [PATCH 2/3] doc on env var precedence wrt config --- docs/concepts/configuration.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index f1b176877..cb89f9fb6 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -66,6 +66,20 @@ In the example above, if we assume the value of the configuration variable ***US During `defang compose up` all variable references will be replaced with the actual value and made available in the container. If any referenced variable is not found the `defang compose up` command will be canceled. +## Environment Variable Precedence + +During a deployment, config vars are exposed to your services as environment variables. Environment variables can be set in multiple places, but Defang uses the following precedence order to determine which value to use: + +:::note +Defang does pass environment variables from the shell into your services. Environment variables must be set in one of the other supported ways listed below. +::: + +1. **Dotenv files**: The `.env` file in the current directory is read by default. This can be overriden per services by specifying the `env_file` service property the `compose.yaml` file. +2. **Docker Compose environment variables**: These are environment variables defined in the `environment` section of the service in the `compose.yaml` file. +3. **Defang config**: These are sensitive configuration values set using the `defang config set FOO=bar` command. + +Environment variables are resolved in order of precedence, with the highest precedence value taking priority. For example, if you have a variable `DATABASE_URL` set in both a dotenv file and in Defang config, the value from Defang config will be used. + ## Using Config with Pulumi In Defang, using config with [Pulumi](./pulumi.md) gives you the advantage of being able to manage your environment variables across different environments using Pulumi stacks. From bd1cdc154c73c529529b9f3ad19fa188d0214e4c Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Thu, 2 Oct 2025 15:28:26 -0700 Subject: [PATCH 3/3] document github actions deployment to aws --- .../deploying-from-github-actions.md | 12 ++ .../deploying-from-github-actions/to-aws.mdx | 174 ++++++++++++++++++ .../deploying-from-github-actions/to-gcp.md | 10 + docs/tutorials/github-actions.md | 84 --------- 4 files changed, 196 insertions(+), 84 deletions(-) create mode 100644 docs/tutorials/deploying-from-github-actions.md create mode 100644 docs/tutorials/deploying-from-github-actions/to-aws.mdx create mode 100644 docs/tutorials/deploying-from-github-actions/to-gcp.md delete mode 100644 docs/tutorials/github-actions.md diff --git a/docs/tutorials/deploying-from-github-actions.md b/docs/tutorials/deploying-from-github-actions.md new file mode 100644 index 000000000..4d4bf72a3 --- /dev/null +++ b/docs/tutorials/deploying-from-github-actions.md @@ -0,0 +1,12 @@ +--- +title: Deploying from GitHub Actions +description: Using the Defang Github Action to deploy your project from your CI/CD pipeline. +--- + +# Deploying from GitHub Actions + +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). + +There is a dedicated tutorial for deploying to each cloud provider: +* [AWS](/docs/tutorials/deploying-from-github-actions/to-aws) +* [GCP](/docs/tutorials/deploying-from-github-actions/to-gcp). diff --git a/docs/tutorials/deploying-from-github-actions/to-aws.mdx b/docs/tutorials/deploying-from-github-actions/to-aws.mdx new file mode 100644 index 000000000..fec235196 --- /dev/null +++ b/docs/tutorials/deploying-from-github-actions/to-aws.mdx @@ -0,0 +1,174 @@ +--- +title: Deploying to AWS from GitHub Actions +description: Using the Defang Github Action to deploy your project to AWS from your CI/CD pipeline. +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +# Deploying to AWS from GitHub Actions + +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. + +## Prerequisites + +- [A Defang Account](/docs/concepts/authentication) +- [A Github Repo](https://docs.github.com/en/get-started/quickstart/create-a-repo) +- [An AWS Account](https://aws.amazon.com) + +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. + +## Step 1 - Identify your AWS Account ID + +To configure the GitHub Action to assume a role in your AWS account, you'll need your AWS Account ID. + + + + ```bash + aws sts get-caller-identity --query Account --output text + 123456789012 # for example + ``` + + + 1. Go to the [AWS Management Console](https://aws.amazon.com/console/). + 2. In the top right corner, click on your account name or number. + 3. Your AWS Account ID will be displayed in the dropdown menu. + + + +## Step 2 - Create an AWS Identity Provider for GitHub Actions + +You will need to create a new OIDC Identity Provider in AWS to enable GitHub Actions to assume roles in your AWS account. + + + + Using the AWS CLI: + + ``` + aws iam create-open-id-connect-provider --client-id-list sts.amazonaws.com --url https://token.actions.githubusercontent.com + ``` + + + Using the AWS Dashboard: + + 1. Go to the [AWS IAM Console](https://console.aws.amazon.com/iam/home#/roles). + 2. Click on "Identity providers" in the left sidebar. + 3. Click on "Add provider". + 4. Choose "OIDC" as the provider type. + 5. For the provider URL, enter `https://token.actions.githubusercontent.com`. + 6. For the audience, enter `sts.amazonaws.com`. + 7. Click "Add provider". + + + +## Step 3 - Create a deployer role with trust relationship for GitHub Actions + + + + Using the AWS CLI: + + 1. Create a trust policy document + + ```bash + cat > deployer-policy.json << EOF + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "*", + "Resource": "*" + }, + { + "Sid": "OidcForGitHub", + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringLike": { + "token.actions.githubusercontent.com:sub": "repo:YOUR_REPO_OWNER/YOUR_REPO_NAME:ref:refs/heads/YOUR_BRANCH_NAME" + }, + "StringEquals": { + "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" + } + } + } + ] + } + EOF + ``` + + 2. Edit the `deployer-policy.json` file to replace the following placeholders: + * `YOUR_AWS_ACCOUNT_ID` replace this with your actual AWS Account ID + * `YOUR_REPO_OWNER` your GitHub username or organization name (e.g., `ACMELabs`) + * `YOUR_REPO_NAME` your GitHub repository name (e.g., `my-project`) + * `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 `*` + + 3. Create a deployer role + ``` + aws iam create-role --role-name deployer --assume-role-policy-document file://deployer-policy.json + ``` + + + + Using the AWS Dashboard: + + 1. Navigate to [AWS IAM Console](https://console.aws.amazon.com/iam/home#/roles). + 2. Click on "Create role". + 3. Select "Web identity" as the trusted entity type. + 4. For the identity provider, select the OIDC provider you created in the previous step. + 5. For the audience, enter `sts.amazonaws.com`. + 6. For the GitHub organization, enter your GitHub username or organization name (e.g., `ACMELabs`). + 7. For the GitHub repository, enter your GitHub repository name (e.g., `my-project`). + 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 `*`. + 9. Click "Next". + 10. Select the `AdministratorAccess` policy to attach to the role. + 11. Click "Next". + 12. For the role name, enter `deployer`. + 13. For the role description, enter "This role is assumed by GitHub Actions when deploying with Defang". + 13. Click "Create role". + + + + +## Step 4 - Create a new GitHub Actions workflow + +In your GitHub repository, create a new file at `.github/workflows/deploy.yml` with the following content: + +```yaml +name: Deploy with Defang +on: + push: + branches: + - 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. +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + + steps: + - name: Configure AWS Credentials for CI + uses: aws-actions/configure-aws-credentials@v4 + with: + aws-region: us-west-2 + # Replace with your AWS Account ID and the name of the role which we previously created. + role-to-assume: arn:aws:iam::123456789012:role/deployer + + - name: Checkout Repo + uses: actions/checkout@v4 + + - name: Deploy + uses: DefangLabs/defang-github-action@v1.2.1 + with: + provider: "aws" +``` + +:::info +Full documentation for configuring AWS can be found in the [Defang GitHub Action repository](https://github.com/DefangLabs/defang-github-action). +::: + +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. diff --git a/docs/tutorials/deploying-from-github-actions/to-gcp.md b/docs/tutorials/deploying-from-github-actions/to-gcp.md new file mode 100644 index 000000000..0880a297c --- /dev/null +++ b/docs/tutorials/deploying-from-github-actions/to-gcp.md @@ -0,0 +1,10 @@ +--- +title: Deploying to GCP from GitHub Actions +description: Using the Defang Github Action to deploy your project to GCP from your CI/CD pipeline. +--- + +# Deploying to GCP from GitHub Actions + +:::info +Coming soon +::: diff --git a/docs/tutorials/github-actions.md b/docs/tutorials/github-actions.md deleted file mode 100644 index 15d2d59f2..000000000 --- a/docs/tutorials/github-actions.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Deploying from GitHub Actions -description: Using the Defang Github Action to deploy your project from your CI/CD pipeline. ---- - -# Deploying from GitHub Actions - -This tutorial will show you how to use the [Defang GitHub Action](https://github.com/DefangLabs/defang-github-action) to deploy your project from your GitHub Actions workflow. - -## Prerequisites - -- [A Defang Account](/docs/concepts/authentication) -- [A Github Repo](https://docs.github.com/en/get-started/quickstart/create-a-repo) - -## Step 1 - Create a new GitHub Actions workflow - -### AWS - -In your GitHub repository, create a new file at `.github/workflows/deploy.yml` with the following content: - -```yaml -name: Deploy to Defang -on: - push: - branches: - - main # Change this to your default branch if it's not 'main' -jobs: - deploy: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - - steps: - - name: Configure AWS Credentials for CI - uses: aws-actions/configure-aws-credentials@v4 - with: - aws-region: us-west-2 - role-to-assume: arn:aws:iam::123456789012:role/ci-role - - - name: Checkout Repo - uses: actions/checkout@v4 - - - name: Deploy - uses: DefangLabs/defang-github-action@v1.2.1 - with: - mode: "balanced" - provider: "aws" -``` - -### GCP - -```yaml -name: Deploy to Defang -on: - push: - branches: - - main # Change this to your default branch if it's not 'main' -jobs: - deploy: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - - steps: - - name: Configure GCP Credentials for Prod - uses: "google-github-actions/auth@v2" - with: - workload_identity_provider: "projects/123456789012/locations/global/workloadIdentityPools/github-actions-pool/providers/my-project-repo-provider" - - - name: Checkout Repo - uses: actions/checkout@v4 - - - name: Deploy - uses: DefangLabs/defang-github-action@v1.2.1 - with: - mode: "balanced" - provider: "gcp" -``` - -Full documentation for configuring AWS and GCP credentials can be found in the [Defang GitHub Action repository](https://github.com/DefangLabs/defang-github-action). - -