Site Creation and Deployment

Skip to end of metadata
Go to start of metadata

Site Creation and Deployment


This page attempts to document some best practices for creating and deploying your plugin's site.


GitHub


GitHub is probably the most common location for Jenkins' plugins. With a few small updates to your plugin's pom.xml you can easily generate and deploy your site to GitHub's pages support.


  • Set up GitHub pages support - http://pages.github.com/ - this will take a few moments to fully activate, so we do it first
  • Update your $HOME/.m2/settings.xml to include a settings.servers.server section:
  <servers>
    <server>
      <id>github-project-site</id>
      <!-- the username really is git, do not change this -->
      <username>git</username>
    </server>
    <!-- ... rest of your servers section ... -->
  </servers>
  • Update your pom.xml to include a project.distributionManagement.site section:
  <distributionManagement>
    <site>
      <id>github-project-site</id>
      <url>gitsite:git@github.com/jenkinsci/your-plugin</url>
    </site>
  </distributionManagement>
  • Update your pom.xml to include a project.properties section:
  <properties>
    <!-- define all plugin versions -->
    <maven.version>3.0.1</maven.version>
    <maven-antrun-plugin.version>1.6</maven-antrun-plugin.version>
    <maven-assembly-plugin.version>2.2</maven-assembly-plugin.version>
    <maven-changelog-plugin.version>2.2</maven-changelog-plugin.version>
    <maven-checkstyle-plugin.version>2.6</maven-checkstyle-plugin.version>
    <maven-clean-plugin.version>2.4.1</maven-clean-plugin.version>
    <maven-compiler-plugin.version>2.3.2</maven-compiler-plugin.version>
    <maven-dependency-plugin.version>2.1</maven-dependency-plugin.version>
    <maven-deploy-plugin.version>2.5</maven-deploy-plugin.version>
    <maven-doap-plugin.version>1.0</maven-doap-plugin.version>
    <maven-eclipse-plugin.version>2.8</maven-eclipse-plugin.version>
    <maven-enforcer-plugin.version>1.0</maven-enforcer-plugin.version>
    <maven-help-plugin.version>2.1.1</maven-help-plugin.version>
    <maven-install-plugin.version>2.3.1</maven-install-plugin.version>
    <maven-javadoc-plugin.version>2.7</maven-javadoc-plugin.version>
    <maven-jar-plugin.version>2.3.1</maven-jar-plugin.version>
    <maven-jetty-plugin.version>6.1.26</maven-jetty-plugin.version>
    <maven-jxr-plugin.version>2.2</maven-jxr-plugin.version>
    <maven-pmd-plugin.version>2.5</maven-pmd-plugin.version>
    <maven-project-info-reports-plugin.version>2.3.1</maven-project-info-reports-plugin.version>
    <maven-plugin-plugin.version>2.4.3</maven-plugin-plugin.version>
    <maven-reactor-plugin.version>1.0</maven-reactor-plugin.version>
    <maven-release-plugin.version>2.1</maven-release-plugin.version>
    <maven-remote-resources-plugin.version>1.1</maven-remote-resources-plugin.version>
    <maven-resources-plugin.version>2.4.3</maven-resources-plugin.version>
    <maven-site-plugin.version>2.1.1</maven-site-plugin.version>
    <maven-source-plugin.version>2.1.2</maven-source-plugin.version>
    <maven-surefire-plugin.version>2.7.2</maven-surefire-plugin.version>
    <maven-surefire-report-plugin.version>2.7.2</maven-surefire-report-plugin.version>
    <maven-war-plugin.version>2.1.1</maven-war-plugin.version>
    <apt-maven-plugin.version>1.0-alpha-4</apt-maven-plugin.version>
    <axistools-maven-plugin.version>1.4</axistools-maven-plugin.version>
    <buildnumber-maven-plugin.version>1.0-beta-4</buildnumber-maven-plugin.version>
    <build-helper-maven-plugin.version>1.5</build-helper-maven-plugin.version>
    <cargo-maven2-plugin.version>1.0.5</cargo-maven2-plugin.version>
    <cobertura-maven-plugin.version>2.4</cobertura-maven-plugin.version>
    <exec-maven-plugin.version>1.2</exec-maven-plugin.version>
    <findbugs-maven-plugin.version>2.3.1</findbugs-maven-plugin.version>
    <gwt-maven-plugin.version>2.1.0-1</gwt-maven-plugin.version>
    <javancss-maven-plugin.version>2.0</javancss-maven-plugin.version>
    <jdepend-maven-plugin.version>2.0-beta-2</jdepend-maven-plugin.version>
    <openjpa-maven-plugin.version>1.2</openjpa-maven-plugin.version>
    <taglist-maven-plugin.version>2.4</taglist-maven-plugin.version>
    <versions-maven-plugin.version>1.2</versions-maven-plugin.version>
    <xml-maven-plugin.version>1.0-beta-3</xml-maven-plugin.version>
  </properties>
  • Update your pom.xml to include a project.build.extensions section:
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-provider-gitexe</artifactId>
        <version>1.3</version>
      </extension>
      <extension>
        <groupId>org.apache.maven.scm</groupId>
        <artifactId>maven-scm-manager-plexus</artifactId>
        <version>1.3</version>
      </extension>
      <extension>
        <groupId>org.kathrynhuxtable.maven.wagon</groupId>
        <artifactId>wagon-gitsite</artifactId>
        <version>0.3.1</version>
      </extension>
    </extensions>
    <!-- ... rest of your build section ... -->
  </build>
  • Update your pom.xml to include a project.build.plugins section:
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-site-plugin</artifactId>
        <version>${maven-site-plugin.version}</version>
      </plugin>
    </plugins>
    <!-- ... rest of your build section ... -->
  </build>
  • Update your pom.xml to include a project.reporting section:
  <reporting>
    <plugins>
      <plugin>
        <artifactId>maven-changelog-plugin</artifactId>
        <version>${maven-changelog-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>${maven-checkstyle-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${maven-javadoc-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-jxr-plugin</artifactId>
        <version>${maven-jxr-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-pmd-plugin</artifactId>
        <version>${maven-pmd-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-plugin-plugin</artifactId>
        <version>${maven-plugin-plugin.version}</version>
      </plugin>
      <plugin>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>${maven-project-info-reports-plugin.version}</version>
        <reportSets>
          <reportSet>
            <reports>
              <report>cim</report>
              <report>distribution-management</report>
              <report>index</report>
              <report>issue-tracking</report>
              <report>license</report>
              <report>mailing-list</report>
              <report>project-team</report>
              <report>scm</report>
              <report>summary</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
      <plugin>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>${maven-surefire-report-plugin.version}</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>cobertura-maven-plugin</artifactId>
        <version>${cobertura-maven-plugin.version}</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>findbugs-maven-plugin</artifactId>
        <version>${findbugs-maven-plugin.version}</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>javancss-maven-plugin</artifactId>
        <version>${javancss-maven-plugin.version}</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>jdepend-maven-plugin</artifactId>
        <version>${jdepend-maven-plugin.version}</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>taglist-maven-plugin</artifactId>
        <version>${taglist-maven-plugin.version}</version>
      </plugin>
    </plugins>
  </reporting>
  • Run the maven commands to generate and deploy the site
mvn site site:deploy


Troubleshooting


  • You need a scm tag in your pom.xml (see http://maven.apache.org/pom.html#SCM)
    • project.scm.connection: scm:git:git://github.com/$GITHUBID/$PROJECTNAME.git (Mind the case of your GitHub-Id and the project name and dont forget the .git!)
    • project.scm.connectionConnection: scm:git:git@github.com:$GITHUBID/$PROJECTNAME.git
    • project.scm.url: https://github.com/_$GITHUBID_/_$PROJECTNAME_/ (No .git at the end!)
  • In project.distributionManagement.site.url: gitsite:git@github.com/GITHUBID/$PROJECTNAME (No .git at the end!)
  • If maven is complaining about that I can not donwload some artifacts: Checking the file permissions of
    ~/.m2/repository may help.
  • Make sure that you use the proper case for all GitHub URLs
    • GitHub is very forgiving about case issues from the web, but not over SSH
  • Make sure that you have .git where you should and not where you shouldn't!
    • It's easy to be overzealous with cut and paste, and the .git extension is specifically required some places
  • Make sure your SSL connection to GitHub is set up properly
    • Ensure you verified ssh git@github.com reports success


References



Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment