Appendix A: GitHub version 1 source actions

To create and register your webhook

1. In a text editor, create and save a JSON file for the webhook you want to create. Use this sample file for a webhook named my-webhook:

   {
       "webhook": {
           "name": "my-webhook",
   	 "targetPipeline": "pipeline_name",
   	 "targetAction": "source_action_name",
   	 "filters": [{
   	     "jsonPath": "$.ref",
   	     "matchEquals": "refs/heads/{Branch}"
   	 }],
   	 "authentication": "GITHUB_HMAC",
   	 "authenticationConfiguration": {
   	     "SecretToken": "secret"
   	 }
       }
   }

2. Call the put-webhook command and include the --cli-input and --region parameters.

   The following sample command creates a webhook with the webhook_json JSON file.

   aws codepipeline put-webhook --cli-input-json file://webhook_json.json --region "eu-central-1"

3. In the output shown in this example, the URL and ARN are returned for a webhook named my-webhook.

   {
       "webhook": {
           "url": "https://webhooks.domain.com/trigger111111111EXAMPLE11111111111111111",
           "definition": {
               "authenticationConfiguration": {
                   "SecretToken": "secret"
               },
               "name": "my-webhook",
               "authentication": "GITHUB_HMAC",
               "targetPipeline": "pipeline_name",
               "targetAction": "Source",
               "filters": [
                   {
                       "jsonPath": "$.ref",
                       "matchEquals": "refs/heads/{Branch}"
                   }
               ]
           },
           "arn": "arn:aws:codepipeline:eu-central-1:ACCOUNT_ID:webhook:my-webhook"
       },
       "tags": [{
         "key": "Project",
         "value": "ProjectA"
       }]
   }

   This example adds tagging to the webhook by including the Project tag key and ProjectA value on the webhook. For more information about tagging resources in CodePipeline, see Tagging resources.

4. Call the register-webhook-with-third-party command and include the --webhook-name parameter.

   The following sample command registers a webhook named my-webhook.

   aws codepipeline register-webhook-with-third-party --webhook-name my-webhook

To edit your pipeline's PollForSourceChanges parameter

1. Run the get-pipeline command to copy the pipeline structure into a JSON file. For example, for a pipeline named MyFirstPipeline, you would type the following command:

   aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

   This command returns nothing, but the file you created should appear in the directory where you ran the command.

2. Open the JSON file in any plain-text editor and edit the source stage by changing or adding the PollForSourceChanges parameter. In this example, for a repository named UserGitHubRepo, the parameter is set to false .

   Why am I making this change? Changing this parameter turns off periodic checks so you can use event-based change detection only.

   "configuration": {
       "Owner": "name",
       "Repo": "UserGitHubRepo",
       "PollForSourceChanges": "false",
       "Branch": "main",
       "OAuthToken": "****"
   },

3. If you are working with the pipeline structure retrieved using the get-pipeline command, you must edit the structure in the JSON file by removing the metadata lines from the file. Otherwise, the update-pipeline command cannot use it. Remove the "metadata" section from the pipeline structure in the JSON file, including the : { } and the "created", "pipelineARN", and "updated" fields.

   For example, remove the following lines from the structure:

   "metadata": {
       "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name",
       "created": "date",
       "updated": "date"
   },

   Save the file.

4. To apply your changes, run the update-pipeline command, specifying the pipeline JSON file, similar to the following:

   Important

   Be sure to include file:// before the file name. It is required in this command.

   aws codepipeline update-pipeline --cli-input-json file://pipeline.json

   This command returns the entire structure of the edited pipeline.

   Note

   The update-pipeline command stops the pipeline. If a revision is being run through the pipeline when you run the update-pipeline command, that run is stopped. You must manually start the pipeline to run that revision through the updated pipeline. Use the start-pipeline-execution command to manually start your pipeline.

To list webhooks in your account

1. To list your webhooks, call the list-webhooks command and include the --endpoint-url and --region parameters.

   The following sample command lists webhooks for the "eu-central-1" endpoint URL.

   aws codepipeline list-webhooks --endpoint-url "https://codepipeline.eu-central-1.amazonaws.com" --region "eu-central-1"

2. Webhooks are listed, including the name and ARN for each webhook.

   {
       "webhooks": [
           {
               "url": "https://webhooks.domain.com/trigger111111111EXAMPLE11111111111111111": {
                   "authenticationConfiguration": {
                       "SecretToken": "Secret"
                   },
                   "name": "my-webhook",
                   "authentication": "GITHUB_HMAC",
                   "targetPipeline": "my-Pipeline",
                   "targetAction": "Source",
                   "filters": [
                       {
                           "jsonPath": "$.ref",
                           "matchEquals": "refs/heads/{Branch}"
                       }
                   ]
               },
               "arn": "arn:aws:codepipeline:eu-central-1:ACCOUNT_ID:webhook:my-webhook"
           }
       ]
   }

3. In GitHub, choose your repository.

4. Choose Settings, and then choose Webhooks.

   View the webhook information for your repository.

Example 1: To update a webhook secret

1. In a text editor, edit the JSON file for the webhook you want to update. This example modifies the sample file that was used to create the webhook in Create a webhook for a GitHub source. This sample changes the secret token of the webhook named "my-webhook".

   {"webhook": 
     {"name": "my-webhook",
      "targetPipeline": "pipeline_name",
      "targetAction": "source_action_name",
      "filters": [
       {
         "jsonPath": "$.ref", 
         "matchEquals": "refs/heads/{Branch}"
       }
      ],
      "authentication": "GITHUB_HMAC",
      "authenticationConfiguration": {"SecretToken":"new_secret"}
     }
   }

2. Call the put-webhook command and include the --cli-input and --region parameters.

   The following sample command updates a webhook with the modified "webhook_json" JSON file.

   aws codepipeline put-webhook --cli-input-json file://webhook_json.json --region "eu-central-1"

3. The output returns the webhook details and the new secret.

   Note

   You can edit the GitHub source action in the console. This allows CodePipeline to manage webhooks for you.

Example 2: To update a webhook name or GitHub repository

1. Use the steps in Delete the webhook for your GitHub source to deregister and delete the existing webhook that is associated with the old webhook name or GitHub repository.

2. Use the steps in Create a webhook for a GitHub source to recreate the webhook.

   Note

   You can edit the GitHub source action in the console. This allows CodePipeline to manage webhooks for you.

1. You must deregister the webhook before you delete it. Call the deregister-webhook-with-third-party command and include the --webhook-name parameter.

   The following sample command deregisters the webhook named "my-webhook".

   aws codepipeline deregister-webhook-with-third-party --webhook-name my-webhook

2. Call the delete-webhook command and include the --name parameter.

   The following sample command deletes the webhook named "my-webhook".

   aws codepipeline delete-webhook --name my-webhook

To add parameters and create a webhook in your template

We strongly recommend that you use Amazon Secrets Manager to store your credentials. If you use Secrets Manager, you must have already configured and stored your secret parameters in Secrets Manager. This example uses dynamic references to Secrets Manager for the GitHub credentials for your webhook. For more information, see Using Dynamic References to Specify Template Values.

When you use the CLI or Amazon CloudFormation to create a pipeline and add a webhook, you must disable periodic checks.

1. In the template, under Resources, add your parameters:

   YAML

   Parameters:
           GitHubOwner:
             Type: String
   
   ...

   JSON

   {
   	"Parameters": {
   		"BranchName": {
   			"Description": "GitHub branch name",
   			"Type": "String",
   			"Default": "main"
   		},
   		"GitHubOwner": {
   			"Type": "String"
   		},
   
   ...

2. Use the AWS::CodePipeline::Webhook Amazon CloudFormation resource to add a webhook.

   Note

   The TargetAction you specify must match the Name property of the source action defined in the pipeline.

   If RegisterWithThirdParty is set to true, make sure the user associated to the OAuthToken can set the required scopes in GitHub. The token and webhook require the following GitHub scopes:

   • repo - used for full control to read and pull artifacts from public and private repositories into a pipeline.

   • admin:repo_hook - used for full control of repository hooks.

   Otherwise, GitHub returns a 404. For more information about the 404 returned, see https://help.github.com/articles/about-webhooks.

   YAML

     AppPipelineWebhook:
       Type: AWS::CodePipeline::Webhook
       Properties:
         Authentication: GITHUB_HMAC
         AuthenticationConfiguration:
           SecretToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}
         Filters:
           - 
             JsonPath: "$.ref"
             MatchEquals: refs/heads/{Branch}
         TargetPipeline: !Ref AppPipeline
         TargetAction: SourceAction
         Name: AppPipelineWebhook
         TargetPipelineVersion: !GetAtt AppPipeline.Version
         RegisterWithThirdParty: true
   
   
   ...

   JSON

   "AppPipelineWebhook": {
       "Type": "AWS::CodePipeline::Webhook",
       "Properties": {
           "Authentication": "GITHUB_HMAC",
           "AuthenticationConfiguration": {
               "SecretToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}"
           },
           "Filters": [{
               "JsonPath": "$.ref",
               "MatchEquals": "refs/heads/{Branch}"
           }],
           "TargetPipeline": {
               "Ref": "AppPipeline"
           },
           "TargetAction": "SourceAction",
           "Name": "AppPipelineWebhook",
           "TargetPipelineVersion": {
               "Fn::GetAtt": [
                 "AppPipeline",
                 "Version"
               ]
           },
           "RegisterWithThirdParty": true
       }
   },
   
   ...

3. Save the updated template to your local computer, and then open the Amazon CloudFormation console.

4. Choose your stack, and then choose Create Change Set for Current Stack.

5. Upload the template, and then view the changes listed in Amazon CloudFormation. These are the changes to be made to the stack. You should see your new resources in the list.

6. Choose Execute.

To edit your pipeline's PollForSourceChanges parameter

• In the template, change PollForSourceChanges to false. If you did not include PollForSourceChanges in your pipeline definition, add it and set it to false.

  Why am I making this change? Changing this parameter to false turns off periodic checks so you can use event-based change detection only.

  YAML

            Name: Source
            Actions: 
              - 
                Name: SourceAction
                ActionTypeId: 
                  Category: Source
                  Owner: ThirdParty
                  Version: 1
                  Provider: GitHub
                OutputArtifacts: 
                  - Name: SourceOutput
                Configuration: 
                  Owner: !Ref GitHubOwner
                  Repo: !Ref RepositoryName
                  Branch: !Ref BranchName
                  OAuthToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}
                  PollForSourceChanges: false
                RunOrder: 1

  JSON

   {
      "Name": "Source",
      "Actions": [{
  	 "Name": "SourceAction",
  	 "ActionTypeId": {
  	     "Category": "Source",
  	     "Owner": "ThirdParty",
  	     "Version": 1,
  	     "Provider": "GitHub"
  	},
  	"OutputArtifacts": [{
  	    "Name": "SourceOutput"
  	}],
  	"Configuration": {
  	    "Owner": {
  		 "Ref": "GitHubOwner"
  	    },
  	    "Repo": {
  		 "Ref": "RepositoryName"
  	    },
  	    "Branch": {
  	        "Ref": "BranchName"
  	    },
  	    "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}",
  	    PollForSourceChanges: false
  	},
  	"RunOrder": 1
      }]

To view your authorized integrations in GitHub

1. In GitHub, from the drop-down option on your profile photo, choose Settings.

2. Choose Applications, and then choose Authorized OAuth Apps.

3. Review your authorized apps.

To create a GitHub personal access token and then update the pipeline structure with the new token

1. In GitHub, from the drop-down option on your profile photo, choose Settings.

2. Choose Developer settings, and then choose Personal access tokens.

3. Choose Generate new token.

   The New personal access token page appears.

4. Under Select scopes, select admin:repo_hook and repo.

5. Choose Generate token.

6. Next to the generated token, choose the copy icon.

   Note

   Make sure you copy your generated token now. You cannot view the token after you close this page.

7. At a terminal (Linux, OS X, or Unix) or command prompt (Windows), run the get-pipeline command on the pipeline where you want to change the OAuth token, and then copy the output of the command to a JSON file. For example, for a pipeline named MyFirstPipeline, you would type something similar to the following:

   aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

   The output of the command is sent to the pipeline.json file.

8. Open the file in a plain-text editor and edit the value in the OAuthTokenField of your GitHub action.

   When you use the Amazon CLI to create the pipeline, you can pass your GitHub personal access token in this field. Replace the asterisks (****) with the token you copied from GitHub. When you run get-pipeline to view the action configuration, the four-asterisk mask is displayed for this value. For example, for a personal access token with the value 111222333444555666777888EXAMPLE:

   "configuration": {
           "Owner": "MyGitHubUserName",
           "Repo": "test-repo",
           "Branch": "main",
           "OAuthToken": "111222333444555666777888EXAMPLE"
       }

   Note

   When you use an Amazon CloudFormation template to create the pipeline, you must first store the token as a secret in Amazon Secrets Manager. You include the value for this field as a dynamic reference to the stored secret in Secrets Manager. For an example, see GitHub version 1 source action structure reference.

9. If you are working with the pipeline structure retrieved using the get-pipeline command, you must modify the structure in the JSON file by removing the metadata lines from the file. Otherwise, the update-pipeline command cannot use it. Remove the section from the pipeline structure in the JSON file (the "metadata": { } lines and the "created", "pipelineARN", and "updated" fields).

   For example, remove the following lines from the structure:

   "metadata": {  
     "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name",
     "created": "date",
     "updated": "date"
     }

10. Save the file, and then run the update-pipeline with the --cli-input-json parameter to specify the JSON file you just edited.

    For example, to update a pipeline named MyFirstPipeline, you would type something similar to the following:

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    Important

    Be sure to include file:// before the file name. It is required in this command.

11. Repeat steps 6 through 8 for every pipeline that contains a GitHub action.

12. When you are finished, delete the JSON files used to update those pipelines.

1. In GitHub, from the drop-down option on your profile photo, choose Settings.

2. Choose Developer settings, and then choose Personal access tokens.

3. Next to your GitHub personal access token, choose Edit.

4. Choose Regenerate token.

5. Next to the regenerated token, choose the copy icon.

6. At a terminal (Linux, OS X, or Unix) or command prompt (Windows), run the get-pipeline command on the pipeline where you want to change the personal access token, and then copy the output of the command to a JSON file. For example, for a pipeline named MyFirstPipeline, you would type something similar to the following:

   aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

   The output of the command is sent to the pipeline.json file.

7. Open the file in a plain-text editor and edit the value in the OAuthTokenField of your GitHub action.

   When you use the Amazon CLI to create the pipeline, you can pass your GitHub personal access token in this field. Replace the asterisks (****) with the token you copied from GitHub. When you run get-pipeline to view the action configuration, the four-asterisk mask is displayed for this value. For example, for a personal access token with the value 111222333444555666777888EXAMPLE:

   "configuration": {
           "Owner": "MyGitHubUserName",
           "Repo": "test-repo",
           "Branch": "main",
           "OAuthToken": "111222333444555666777888EXAMPLE"
       }

   Note

   When you use an Amazon CloudFormation template to update the pipeline, you must first store the token as a secret in Amazon Secrets Manager. You include the value for this field as a dynamic reference to the stored secret in Secrets Manager. For an example, see GitHub version 1 source action structure reference.

8. If you are working with the pipeline structure retrieved using the get-pipeline command, you must modify the structure in the JSON file by removing the metadata lines from the file. Otherwise, the update-pipeline command cannot use it. Remove the section from the pipeline structure in the JSON file (the "metadata": { } lines and the "created", "pipelineARN", and "updated" fields).

   For example, remove the following lines from the structure:

   "metadata": {  
     "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name",
     "created": "date",
     "updated": "date"
     }

9. Save the file, and then run update-pipeline with the --cli-input-json parameter to specify the JSON file you just edited. For example, to update a pipeline named MyFirstPipeline, you would type something similar to the following:

   Important

   Be sure to include file:// before the file name. It is required in this command.

   aws codepipeline update-pipeline --cli-input-json file://pipeline.json

10. When you have finished updating your pipelines, delete the JSON files.

To create your stack in Amazon CloudFormation

1. Unzip the files from SampleApp_Linux.zip and upload the files to your GitHub repository. You must upload the unzipped files to the root directory of your repository.

2. Open the Amazon CloudFormation console and choose Create Stack.

3. In Choose a template, choose Upload a template to Amazon S3. Choose Browse, and then select the template file from your local computer. Choose Next.

4. In Stack name, enter a name for your pipeline. Parameters specified by the sample template are displayed. Enter the following parameters:

   1. In ApplicationName, enter the name of your CodeDeploy application.

   2. In BetaFleet, enter the name of your CodeDeploy deployment group.

   3. In BranchName, enter the repository branch you want to use.

   4. In GitHubOAuthToken, enter the personal access key for your GitHub repository.

   5. In GitHubOwner, enter the GitHub user name for the owner of the repository.

   6. In GitHubSecret, enter the secret you want to use for the webhook Amazon CloudFormation creates.

   7. In RepositoryName, enter the name of your GitHub source repository.

5. Choose Next. Accept the defaults on the following page, and then choose Next.

6. In Capabilities, select I acknowledge that Amazon CloudFormation might create IAM resources, and then choose Create.

7. After your stack creation is complete, view the event list to check for any errors.

8. Sign in to the Amazon Web Services Management Console and open the CodePipeline console at https://console.amazonaws.cn/codepipeline/.

   Under Pipelines, choose your pipeline, and then choose View. The diagram shows your pipeline source and deployment stages.

9. In your source repository, commit and push a change. Your change-detection resources pick up the change and your pipeline starts.

1. Check to see if the permissions for CodePipeline have been revoked. For the steps to check the Authorized OAuth Apps list in GitHub, see View your authorized OAuth apps. If you do not see CodePipeline in the list, you must use the console to reconnect your pipeline to GitHub.

   1. Open your pipeline in the console and choose Edit. On the source stage that contains your GitHub source action, choose Edit stage.

   2. On the GitHub source action, choose the edit icon.

   3. On the Edit action page, choose Connect to GitHub to restore the authorization.

      If prompted, you might need to re-enter the Repository and Branch for your action. Choose Done. Choose Done on the stage editing page, and then choose Save on the pipeline editing page. Run the pipeline.

2. If this does not correct the error but you can see CodePipeline in the Authorized OAuth Apps list in GitHub, you might have exceeded the allowed number of tokens. To fix this issue, you can manually configure one OAuth token as a personal access token, and then configure all pipelines in your Amazon account to use that token. For more information, see Configure your pipeline to use a personal access token (GitHub and CLI).