Appendix A: GitHub version 1 source actions - AWS CodePipeline
Adding a GitHub version 1 source actionGitHub version 1 source action structure reference

Appendix A: GitHub version 1 source actions

This appendix provides information about version 1 of the GitHub action in CodePipeline.

Note

While we don’t recommend using the GitHub version 1 action, existing pipelines with the GitHub version 1 action will continue to work without any impact. For a pipeline with a GitHub version 1 action, CodePipeline uses OAuth-based tokens to connect to your GitHub repository. By contrast, the GitHub action (version 2) uses a connection resource to associate AWS resources to your GitHub repository. The connection resource uses app-based tokens to connect. For more information about updating your pipeline to the recommended GitHub action that uses a connection, see Update a GitHub version 1 source action to a GitHub version 2 source action. For more information about OAuth-based GitHub access in contrast to app-based GitHub access, see https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps.

To integrate with GitHub, CodePipeline uses a GitHub OAuth application for your pipeline. CodePipeline uses webhooks to manage change detection for your pipeline with the GitHub version 1 source action.

Note

When you configure a GitHub version 2 source action in AWS CloudFormation, you do not include any GitHub token information or add a webhook resource. You configure a connections resource as shown in AWS::CodeStarConnections::Connection in the AWS CloudFormation User Guide.

This reference contains the following sections for the GitHub version 1 action:

Adding a GitHub version 1 source action

You add GitHub version 1 source actions to CodePipeline by:

  • Using the CodePipeline console Create pipeline wizard (Create a pipeline (console)) or Edit action page to choose the GitHub provider option. The console creates a webhook that starts your pipeline when the source changes.

  • Using the CLI to add the action configuration for the GitHub action and creating additional resources as follows:

    • Using the GitHub example action configuration in GitHub version 1 source action structure reference to create the action as shown in Create a pipeline (CLI).

    • Disabling periodic checks and creating the change detection manually, because the change detection method defaults to starting the pipeline by polling the source. You migrate your polling pipeline to webhooks for GitHub Version 1 actions.

GitHub version 1 source action structure reference

Note

While we don’t recommend using the GitHub version 1 action, existing pipelines with the GitHub version 1 action will continue to work without any impact. For a pipeline with a GitHub GitHub version 1 source action, CodePipeline uses OAuth-based tokens to connect to your GitHub repository. By contrast, the new GitHub action (version 2) uses a connection resource to associate AWS resources to your GitHub repository. The connection resource uses app-based tokens to connect. For more information about updating your pipeline to the recommended GitHub action that uses a connection, see Update a GitHub version 1 source action to a GitHub version 2 source action.

Triggers the pipeline when a new commit is made on the configured GitHub repository and branch.

To integrate with GitHub, CodePipeline uses an OAuth application or a personal access token for your pipeline. If you use the console to create or edit your pipeline, CodePipeline creates a GitHub webhook that starts your pipeline when a change occurs in the repository.

You must have already created a GitHub account and repository before you connect the pipeline through a GitHub action.

If you want to limit the access CodePipeline has to repositories, create a GitHub account and grant the account access only to those repositories you want to integrate with CodePipeline. Use that account when you configure CodePipeline to use GitHub repositories for source stages in pipelines.

For more information, see the GitHub developer documentation on the GitHub website.

Action type

  • Category: Source

  • Owner: ThirdParty

  • Provider: GitHub

  • Version: 1

Configuration parameters

Owner

Required: Yes

The name of the GitHub user or organization who owns the GitHub repository.

Repo

Required: Yes

The name of the repository where source changes are to be detected.

Branch

Required: Yes

The name of the branch where source changes are to be detected.

OAuthToken

Required: Yes

Represents the GitHub authentication token that allows CodePipeline to perform operations on your GitHub repository. The entry is always displayed as a mask of four asterisks. It represents one of the following values:

  • When you use the console to create the pipeline, CodePipeline uses an OAuth token to register the GitHub connection.

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

  • When you use an AWS CloudFormation template to create the pipeline, you must first store the token as a secret in AWS Secrets Manager. You include the value for this field as a dynamic reference to the stored secret in Secrets Manager, such as {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}.

For more information about GitHub scopes, see the GitHub Developer API Reference on the GitHub website.

PollForSourceChanges

Required: No

PollForSourceChanges controls whether CodePipeline polls the GitHub repository for source changes. We recommend that you use webhooks to detect source changes instead. For more information about configuring webhooks, see Migrate polling pipelines to webhooks (GitHub version 1 source actions) (CLI) or Update pipelines for push events (GitHub version 1 source actions) (AWS CloudFormation template).

Important

If you intend to configure webhooks, you must set PollForSourceChanges to false to avoid duplicate pipeline executions.

Valid values for this parameter:

  • True: If set, CodePipeline polls your repository for source changes.

    Note

    If you omit PollForSourceChanges, CodePipeline defaults to polling your repository for source changes. This behavior is the same as if PollForSourceChanges is set to true.

  • False: If set, CodePipeline does not poll your repository for source changes. Use this setting if you intend to configure a webhook to detect source changes.

Input artifacts

  • Number of artifacts: 0

  • Description: Input artifacts do not apply for this action type.

Output artifacts

  • Number of artifacts: 1

  • Description: The output artifact of this action is a ZIP file that contains the contents of the configured repository and branch at the commit specified as the source revision for the pipeline execution. The artifacts generated from the repository are the output artifacts for the GitHub action. The source code commit ID is displayed in CodePipeline as the source revision for the triggered pipeline execution.

Output variables

When configured, this action produces variables that can be referenced by the action configuration of a downstream action in the pipeline. This action produces variables which can be viewed as output variables, even if the action doesn't have a namespace. You configure an action with a namespace to make those variables available to the configuration of downstream actions.

For more information about variables in CodePipeline, see Variables.

CommitId

The GitHub commit ID that triggered the pipeline execution. Commit IDs are the full SHA of the commit.

CommitMessage

The description message, if any, associated with the commit that triggered the pipeline execution.

CommitUrl

The URL address for the commit that triggered the pipeline.

RepositoryName

The name of the GitHub repository where the commit that triggered the pipeline was made.

BranchName

The name of the branch for the GitHub repository where the source change was made.

AuthorDate

The date when the commit was authored, in timestamp format.

For more information about the difference between an author and a committer in Git, see Viewing the Commit History in Pro Git by Scott Chacon and Ben Straub.

CommitterDate

The date when the commit was committed, in timestamp format.

For more information about the difference between an author and a committer in Git, see Viewing the Commit History in Pro Git by Scott Chacon and Ben Straub.

Action declaration (GitHub example)

YAML
Name: Source
Actions:
  - InputArtifacts: []
    ActionTypeId:
      Version: '1'
      Owner: ThirdParty
      Category: Source
      Provider: GitHub
    OutputArtifacts:
      - Name: SourceArtifact
    RunOrder: 1
    Configuration:
      Owner: MyGitHubAccountName
      Repo: MyGitHubRepositoryName
      PollForSourceChanges: 'false'
      Branch: main
      OAuthToken: '{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}'
    Name: ApplicationSource
JSON
{
    "Name": "Source",
    "Actions": [
        {
            "InputArtifacts": [],
            "ActionTypeId": {
                "Version": "1",
                "Owner": "ThirdParty",
                "Category": "Source",
                "Provider": "GitHub"
            },
            "OutputArtifacts": [
                {
                    "Name": "SourceArtifact"
                }
            ],
            "RunOrder": 1,
            "Configuration": {
                "Owner": "MyGitHubAccountName",
                "Repo": "MyGitHubRepositoryName",
                "PollForSourceChanges": "false",
                "Branch": "main",
                "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}"
            },
            "Name": "ApplicationSource"
        }
    ]
},

Connecting to GitHub (OAuth)

The first time you use the console to add a GitHub repository to a pipeline, you are asked to authorize CodePipeline access to your repositories. The token requires the following GitHub scopes:

  • The repo scope, which is used for full control to read and pull artifacts from public and private repositories into a pipeline.

  • The admin:repo_hook scope, which is used for full control of repository hooks.

When you use the CLI or an AWS CloudFormation template, you must provide the value for a personal access token that you have already created in GitHub.

The following related resources can help you as you work with this action.