Create docs for continuous integration

[mattkinnersley]

This PR creates a page for setting up GitHub actions to deploy an SST application.

[jayair]

Nice, yeah let me review and edit it. I might not get to it this week.

[iliaamiri]

@mattkinnersley

This PR creates a page for setting up GitHub actions to deploy an SST application.

Out of curiosity, how does it authenticate on AWS without a token? AWS Account Id is not considered sensitive data.

Is it working with cloudfront API token?

[mattkinnersley]

@mattkinnersley

This PR creates a page for setting up GitHub actions to deploy an SST application.

Out of curiosity, how does it authenticate on AWS without a token? AWS Account Id is not considered sensitive data.

Is it working with cloudfront API token?

@iliaamiri When we set up the Identity Provider in our SST config, we give it our GitHub org and repo name. We also give it a URL which in our case is the generic GitHub actions URL. These tell AWS that if anything is trying to assume a role in our account from a GitHub action running in our exact repo, then allow it. So for deploying to AWS from a GitHub action, we can use short lived tokens that are generated when the action runs. To the best of my knowledge, Cloudflare doesn't have this kind of Identity Provider/ Assume Role mechanism, so we simply provide a token to the GitHub action which should be scoped to do only what you need it to do.

[iliaamiri]

@mattkinnersley

Appreciated the thorough explanation. Makes total sense. I guess It'd be great to also add instructions for IAM Identity Center too for beginners like me. (Instructions on how to setup the AWS side basically)

[xinha-sh]

@mattkinnersley Should the thumbprintLists value be stored as a secret ?

const oidc = new aws.iam.OpenIdConnectProvider("GithubOidc", {
    clientIdLists: ["sts.amazonaws.com"],
    thumbprintLists: ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
    url: `https://token.actions.githubusercontent.com`,
  });

[mattkinnersley]

@mattkinnersley Should the thumbprintLists value be stored as a secret ?

const oidc = new aws.iam.OpenIdConnectProvider("GithubOidc", {

    clientIdLists: ["sts.amazonaws.com"],

    thumbprintLists: ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],

    url: `https://token.actions.githubusercontent.com`,

  });

@xinha-sh No you don't need to store it as a secret, the value is actually completely arbitrary and could be anything. AWS has GitHub as a recognised provider and already knows the thumbprint. Pulumi, however, haven't updated their SDK to reflect this value isn't needed so we need to provide a value just to satisfy the expected type.

[xinha-sh]

@mattkinnersley This documentation basically uses one AWS org for different stages right ? What changes needs to be done in order to use different aws organization / child organization aws-sso for different stages ?

[iliaamiri]

This PR creates a page for setting up GitHub actions to deploy an SST application.

Hey man, I just wanted to appreciate this documentation. I just got the company's Next.js CD pipelines automated in GitHub action, and I'm so happy about it. Huge thanks to you! You rock! :partying_face:

[mattkinnersley]

@mattkinnersley This documentation basically uses one AWS org for different stages right ? What changes needs to be done in order to use different aws organization / child organization aws-sso for different stages ?

@xinha-sh No this works with AWS SSO which is what I use. You just need to set the correct account number as a variable in your GitHub repo settings.

[iliaamiri]

I've discovered a few possible caveats

My custom use case let me discover some caveats that people might end up experiencing:

1. If you remove any stage of your app, it can possibly remove the OIDC as well. This can cause the rest of the stages to not be able to authenticate on AWS in the runner (on GitHub actions) because there is no Identity Providers anymore. Possible solution: manually create the GitHub OIDC on your IAM console and get its ARN like this:

   
   const oidc = await aws.iam.getOpenIdConnectProvider({
   url: 'https://token.actions.githubusercontent.com',
   });

// oidc.arn

2. The name of the GitHub role is too generic. The role being generic limits you with how many different projects you want to use this for. 
**Possible solution**: name the role as `${$app.stage}-${$app.name}-GithubRole`.

It would be great if we could tell SST not to remove these things specifically.

### Update
I ended up manually creating the github roles on AWS. This was a requirement for my case because in the long run, removing a stage would remove the role. And can potentially cause outage in the pipeline automation. 

That's not to say this isn't helpful. I couldn't do this without these docs. 🙏 

[mattkinnersley]

I've discovered a few possible caveats

My custom use case let me discover some caveats that people might end up experiencing:

1. If you remove any stage of your app, it can possibly remove the OIDC as well. This can cause the rest of the stages to not be able to authenticate on AWS in the runner (on GitHub actions) because there is no Identity Providers anymore.

Possible solution: manually create the GitHub OIDC on your IAM console and get its ARN like this:

const oidc = await aws.iam.getOpenIdConnectProvider({

  url: 'https://token.actions.githubusercontent.com',

});

// oidc.arn

2. The name of the GitHub role is too generic. The role being generic limits you with how many different projects you want to use this for.

Possible solution: name the role as ${$app.stage}-${$app.name}-GithubRole.

It would be great if we could tell SST not to remove these things specifically.

Update

I ended up manually creating the github roles on AWS. This was a requirement for my case because in the long run, removing a stage would remove the role. And can potentially cause outage in the pipeline automation.

That's not to say this isn't helpful. I couldn't do this without these docs. 🙏

Thanks @iliaamiri those are good points. I think these docs will likely be improved by pointing people towards using the SST console with all the work they're doing on autodeploy

[mattkinnersley]

Closing at Console now supports CI