components/camel-github/src/main/docs/github-component.adoc

= GitHub Component
:doctitle: GitHub
:shortname: github
:artifactid: camel-github
:description: Interact with the GitHub API.
:since: 2.15
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: github

*Since Camel {since}*

*{component-header}*

The GitHub component interacts with the GitHub API by
encapsulating https://git.eclipse.org/c/egit/egit-github.git/[egit-github]. It
currently provides polling for new pull requests, pull request comments,
tags, and commits.  It is also able to produce comments on pull
requests, as well as close the pull request entirely.

Rather than webhooks, this endpoint relies on simple polling. Reasons
include:

* Concern for reliability/stability
* The types of payloads we're polling aren't typically large (plus,
paging is available in the API)
* The need to support apps running somewhere not publicly accessible
where a webhook would fail

Note that the GitHub API is fairly expansive.  Therefore, this component
could be easily expanded to provide additional interactions.

Maven users will need to add the following dependency to their pom.xml
for this component:

[source,xml]
-----------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-github</artifactId>
    <version>${camel-version}</version>
</dependency>
-----------------------------------------

== URI format

---------------------------
github://endpoint[?options]
---------------------------


// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END

// component headers: START
include::partial$component-endpoint-headers.adoc[]
// component headers: END

== Configuring authentication

The github component requires to be configured with an authentication token on either the component or endpoint level.

For example to set it on the component:

[source,java]
----
GitHubComponent ghc = context.getComponent("github", GitHubComponent.class);
ghc.setOauthToken("mytoken");
----

== Consumer Endpoints:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Endpoint |Context |Body Type

|pullRequest |polling |org.eclipse.egit.github.core.PullRequest

|pullRequestComment |polling |org.eclipse.egit.github.core.Comment (comment on the general pull
request discussion) or org.eclipse.egit.github.core.CommitComment
(inline comment on a pull request diff)

|tag |polling |org.eclipse.egit.github.core.RepositoryTag

|commit |polling |org.eclipse.egit.github.core.RepositoryCommit
|=======================================================================

== Producer Endpoints:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Endpoint |Body |Message Headers

|pullRequestComment |String (comment text) | - GitHubPullRequest (integer) (REQUIRED): Pull request number.

- GitHubInResponseTo (integer): Required if responding to another inline
comment on the pull request diff. If left off, a general comment on the
pull request discussion is assumed.

|closePullRequest |none | - GitHubPullRequest (integer) (REQUIRED): Pull request number.

|createIssue |String (issue body text) | - GitHubIssueTitle (String) (REQUIRED): Issue Title.
|=======================================================================


include::spring-boot:partial$starter.adoc[]