Quickstart for GitHub Packages

Publish to GitHub Packages in 5 minutes or less with GitHub Actions.

In this article

Introduction

You only need an existing GitHub repository to publish a package to GitHub Packages. In this guide, you'll create a GitHub Actions workflow to test your code and then publish it to GitHub Packages. Feel free to create a new repository for this Quickstart. You can use it to test this and future GitHub Actions workflows.

Publishing your package

  1. Create a new repository on GitHub, adding the .gitignore for Node. For more information, see "Creating a new repository."

  2. Clone the repository to your local machine.

    $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
    $ cd YOUR-REPOSITORY
  3. Create an index.js file and add a basic alert to say "Hello world!"

    JavaScript
    alert("Hello, World!");
  4. Initialize an npm package. In the package initialization wizard, enter your package with the name: @YOUR-USERNAME/YOUR-REPOSITORY, and set the test script to exit 0 if you do not have any tests. Commit your changes and push them to GitHub.

    $ npm init
      ...
      package name: @YOUR-USERNAME/YOUR-REPOSITORY
      ...
      test command: exit 0
      ...
    
    $ npm install
    $ git add index.js package.json package-lock.json
    $ git commit -m "initialize npm package"
    $ git push
  5. From your repository on GitHub, create a new file in the .github/workflows directory named release-package.yml. For more information, see "Creating new files."

  6. Copy the following YAML content into the release-package.yml file.

    YAML
    name: Node.js Package
    
    on:
      release:
        types: [created]
    
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v2
          - uses: actions/setup-node@v1
            with:
              node-version: 12
          - run: npm ci
          - run: npm test
    
      publish-gpr:
        needs: build
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v2
          - uses: actions/setup-node@v1
            with:
              node-version: 12
              registry-url: https://npm.pkg.github.com/
          - run: npm ci
          - run: npm publish
            env:
              NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
  7. Scroll to the bottom of the page and select Create a new branch for this commit and start a pull request. Then, to create a pull request, click Propose new file.

  8. Merge the pull request.

  9. Navigate to the Code tab and create a new release to test the workflow. For more information, see "Managing releases in a repository."

Creating a new release in your repository triggers the workflow to build and test your code. If the tests pass, then the package will be published to GitHub Packages.

Viewing your published package

Packages are published at the repository level. You can see all the packages in a repository and search for a specific package.

  1. On GitHub, navigate to the main page of the repository.

  2. To the right of the list of files, click Packages.

    Packages link on repo overview page

  3. Click the name of the package that you want to view.

    Package name

Installing a published package

Now that you've published the package, you'll want to use it as a dependency across your projects. For more information, see "Configuring npm for use with GitHub Packages."

Next steps

The basic workflow you just added runs any time a new release is created in your repository. But, this is only the beginning of what you can do with GitHub Packages. You can publish your package to multiple registries with a single workflow, trigger the workflow to run on different events such as a merged pull request, manage containers, and more.

Combining GitHub Packages and GitHub Actions can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with GitHub Packages and GitHub Actions:

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.