Skip to content

github: document auth input options #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

github: document auth input options #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2d9145e
github: document auth input options
benbroadaway Oct 17, 2025
a52f435
fix typos
benbroadaway Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 119 additions & 31 deletions docs/plugins-v1/git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ task.
- [Merge Local Branches](#merge-local-branches)
- [GitHub Task](#github-task)
- [Common Task Parameters](#common-task-parameters)
- [`auth` Examples](#auth-examples)
- [Create and Delete a Repository](#githubRepo)
- [Create and Merge a Pull Request](#pr)
- [Comment on a Pull Request](#commentPR)
Expand Down Expand Up @@ -368,8 +369,9 @@ configuration:
The authors of specific projects on the Concord server can then specify the
remaining parameters:

- `accessToken`: required, the GitHub
[access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
- `auth`: required, the GitHub API [authentication details](#auth-examples). Either
an [access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
or a [GitHub App installation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
- `org`: required, the name of the GitHub organization or user in which the git
repository is located.
- `repo`: required, the name of the git repository.
Expand All @@ -383,13 +385,82 @@ flows:
in:
action: "createPr"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
```

Examples below take advantage of a globally configured `apiUrl`.

## Common Task Parameters

The following input parameters are required for all `github` task calls.
`action`-specific parameters are detailed in the action's docs.

- `action`: Task action to perform
- `apiUrl`: GitHub API URL (e.g. `https://github.example.com/api/v3`)
- `auth`: API authentication. Must include **exactly one** of the following:
- `accessToken`: String, Access token for GitHub API. Must have appropriate
[scope](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps)
- `appInstallation`: Object/Map, GitHub App installation details
- `clientId`: String, GitHub App client ID.
- `privateKey`: String, PEM-encoded app private key generated by GitHub
- `refreshBufferSeconds`: (optional) Number, time in seconds before token expiration to
refresh the token. Default is `60` seconds.
- `appInstallationSecret`: Reference to Concord secret containing GitHub App installation
details in JSON format.
- `org`: String, secret organization
- `name`: String, secret name

### `auth` examples

#### GitHub App Installation Secret

Store the app installation details in a Concord single value Secret using JSON format.

```json
{
"clientId": "abc123",
"privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n",
"refreshBufferSeconds": 60
}
```

Then reference the secret in the `github` task call:

```yaml
- task: github
in:
auth:
appInstallationSecret:
org: Default
name: task-test-auth.json
```

#### Inline GitHub App Installation Details

Similarly, the app installation details can be provided inline. (The private key
should still be sourced from a secret store).

```yaml
- task: github
in:
auth:
appInstallation:
clientId: "abc123"
privateKey: "${crypto.exportAsString('my-org', 'my-app-pk', null)}"
```

#### Access Token

```yaml
- task: github
in:
auth:
accessToken: "${crypto.exportAsString('my-org', 'my-access-token', null)}"
```

<a name="githubRepo"/>

## Create and Delete a Repository
Expand Down Expand Up @@ -419,7 +490,8 @@ flows:
in:
action: "createRepo"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myRepository"
repo: "myOrg"

Expand All @@ -444,7 +516,8 @@ flows:
in:
action: "deleteRepo"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myRepository"
repo: "myOrg"
```
Expand Down Expand Up @@ -491,7 +564,8 @@ flows:
- task: github
in:
action: "createPr"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prTitle: "Feature A"
Expand Down Expand Up @@ -525,7 +599,8 @@ flows:
- task: github
in:
action: "mergePr"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
Expand All @@ -545,7 +620,7 @@ parameter from the `createPr` action.

The example below uses the pull request identifier `myPrId`, that was populated
with a value in the `createPr` action above. `prComment` is the string that is
posted to the pull request as a comment. The `accessToken` used determines the
posted to the pull request as a comment. The `auth` used determines the
user adding the comment.

**`commentPR` Parameters:**
Expand All @@ -561,7 +636,8 @@ flows:
- task: github
in:
action: "commentPR"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
Expand Down Expand Up @@ -590,7 +666,8 @@ flows:
- task: github
in:
action: "closePR"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
Expand Down Expand Up @@ -621,7 +698,8 @@ flows:
- task: github
in:
action: "createTag"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
tagVersion: "1.0.0"
Expand All @@ -648,12 +726,13 @@ The `deleteTag` action of the `github` task can be used to delete an existing
flows:
default:
- task: github
in:
action: "deleteTag"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
tagName: "myTagName"
in:
action: "deleteTag"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
tagName: "myTagName"
```

<a name="deleteBranch"/>
Expand All @@ -673,12 +752,13 @@ The `deleteBranch` action of the `github` task can be used to delete an existing
flows:
default:
- task: github
in:
action: "deleteBranch"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
branch: myBranchName
in:
action: "deleteBranch"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
branch: myBranchName
```

<a name="github-merge"/>
Expand Down Expand Up @@ -711,7 +791,8 @@ flows:
- task: github
in:
action: "merge"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
base: "master"
Expand Down Expand Up @@ -741,7 +822,8 @@ flows:
- task: github
in:
action: "forkRepo"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
targetOrg: "myForkToOrg"
Expand Down Expand Up @@ -771,7 +853,8 @@ flows:
- task: github
in:
action: getBranchList
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"

Expand Down Expand Up @@ -801,7 +884,8 @@ flows:
- task: github
in:
action: "getTagList"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"

Expand Down Expand Up @@ -833,7 +917,8 @@ flows:
- task: github
in:
action: "getPR"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prNumber: 123
Expand Down Expand Up @@ -868,7 +953,8 @@ flows:
- task: github
in:
action: getPRList
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
state: "closed"
Expand Down Expand Up @@ -906,7 +992,8 @@ flows:
- task: github
in:
action: "getLatestSHA"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
branch: "myBranch"
Expand Down Expand Up @@ -935,7 +1022,8 @@ flows:
- task: github
in:
action: "addStatus"
accessToken: "myGitHubToken"
auth:
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
commitSHA: "dfd5...0262"
Expand Down
Loading