Skip to content

Commit

Permalink
updates for ga (#46)
Browse files Browse the repository at this point in the history
* updates for ga

* Update README.md

* Add detailed plugin docs

* Remove ghcr credentials from cli

---------

Co-authored-by: Ethan Dennis <[email protected]>
Co-authored-by: Ethan Dennis <[email protected]>
  • Loading branch information
3 people authored Mar 1, 2023
1 parent 627564a commit 0fb03fa
Show file tree
Hide file tree
Showing 363 changed files with 17,073 additions and 394 deletions.
12 changes: 0 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,6 @@ Please note that this project is released with a [Contributor Code of Conduct](C

Here's some helpful notes on how to contribute to this project, including details on how to get started working the codebase.

## How to submit a bug or request a feature

If you think you've found a bug or have a great idea for new functionality please create an issue in this repo.

## How to provide feedback or ask for help

Use the [Discussions](https://github.com/github/gh-actions-importer/discussions) tab in this repo for more general feedback or any questions/comments on this tooling.

## Configure your development environment

To get started, you'll need [.NET Core 6.0](https://dotnet.microsoft.com/en-us/download) installed on your local machine.
Expand All @@ -37,7 +29,3 @@ Code linting can be run using the following command:
```bash
$ dotnet format src/ActionsImporter.sln
```

## Submitting a Pull Request

Before submitting a Pull Request please first open an issue to get feedback on the change you intend to submit.
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2022 GitHub
Copyright (c) 2023 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
146 changes: 25 additions & 121 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,25 @@

[![.github/workflows/ci.yml](https://github.com/github/gh-actions-importer/actions/workflows/ci.yml/badge.svg)](https://github.com/github/gh-actions-importer/actions/workflows/ci.yml)

[GitHub Actions Importer](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-github-actions-importer) helps plan, forecast, and automate the migration of Azure DevOps, CircleCI, GitLab, Jenkins, and Travis CI pipelines to GitHub Actions. This repository provides functionality that extends the [GitHub CLI](https://cli.github.com/) to migrate pipelines using the GitHub Actions Importer.

> **Note**: Sign up [here](https://github.com/features/actions-importer/signup) to request access to the public preview for GitHub Actions Importer. Once you are granted access you'll be able to use the `gh-actions-importer` CLI extension
You can request support [here](https://support.github.com/contact?tags=actions_importer_beta) on a best-effort basis during the public preview period.

## Supported platforms

GitHub Actions Importer currently supports migrating pipelines to GitHub Actions from the following platforms:
[GitHub Actions Importer](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-github-actions-importer) helps plan, test, and automate your migration to GitHub Actions from the following platforms:

- Azure DevOps
- CircleCI
- GitLab
- Jenkins
- Travis CI

You can find detailed information about how the GitHub Actions Importer works for each of the supported platforms in the documentation that is available once you are granted access.

## Getting started with GitHub Actions Importer
## Getting started

GitHub Actions Importer is distributed as a Docker container and this extension to the official [GitHub CLI](https://cli.github.com) to interact with the Docker container.

### Prerequisites

The following requirements must be met to be able to use the GitHub Actions Importer:

- The Docker CLI must be [installed](https://docs.docker.com/get-docker/) and running
- The official [GitHub CLI](https://cli.github.com) must be installed
- You must have credentials to [authenticate](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry) with the GitHub Container Registry after you are granted access.
- The Docker CLI must be [installed](https://docs.docker.com/get-docker/) and running.
- The official [GitHub CLI](https://cli.github.com) must be installed.
- You must have credentials to [authenticate](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry) with the GitHub Container Registry.

### Installation

Expand All @@ -40,26 +30,9 @@ Next, the GitHub Actions Importer CLI extension can be installed via this comman
$ gh extension install github/gh-actions-importer
```

To verify the extension is installed, run this command:

```bash
$ gh actions-importer -h
Options:
-?, -h, --help Show help and usage information

Commands:
update Update to the latest version of the GitHub Actions Importer.
version Display the version of the GitHub Actions Importer.
configure Start an interactive prompt to configure credentials used to authenticate with your CI server(s).
audit Plan your CI/CD migration by analyzing your current CI/CD footprint.
forecast Forecast GitHub Actions usage from historical pipeline utilization.
dry-run Convert a pipeline to a GitHub Actions workflow and output its yaml file.
migrate Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.
```

### Configuration

New versions of the GitHub Actions Importer are released on a regular basis. To ensure you're always up to date, the following command should be run often:
New versions of the GitHub Actions Importer are released on a regular basis. To ensure you're up to date, run the following command:

```bash
$ gh actions-importer update
Expand All @@ -71,109 +44,40 @@ $ gh actions-importer update
$ echo $GITHUB_TOKEN | gh actions-importer update --username $GITHUB_HANDLE --password-stdin
```

In order for the GitHub Actions Importer to communicate with your current CI/CD server and GitHub, various credentials must be available for the command. These can be configured using environment variables or a `.env.local` file. These environment variables can be configured in an interactive prompt by running the following command:
In order for GitHub Actions Importer to communicate with your current CI/CD server and GitHub, various credentials must be available for the command. These can be configured using environment variables or a `.env.local` file. These environment variables can be configured in an interactive prompt by running the following command:

```bash
$ gh actions-importer configure
? Enter value for 'GITHUB_ACCESS_TOKEN' (leave empty to skip):
...
```

You can find detailed information about using environment variables in the documentation that is available once you are granted access.

### Usage

Now that the GitHub Actions Importer is configured and up-to-date, different subcommands of `gh actions-importer` can be used to migrate to GitHub Actions.

#### Audit

The `audit` subcommand can be used to plan your CI/CD migration by analyzing your current CI/CD footprint. This analysis can then be used to plan timelines for migrating to GitHub Actions.

To run an audit, use the following command to determine the options that are relevant to your use case:

```bash
$ gh actions-importer audit -h
Description:
Plan your CI/CD migration by analyzing your current CI/CD footprint.

[...]

Commands:
azure-devops An audit will output a list of data used in an Azure DevOps instance.
circle-ci An audit will output a list of data used in a CircleCI instance.
gitlab An audit will output a list of data used in a GitLab instance.
jenkins An audit will output a list of data used in a Jenkins instance.
travis-ci An audit will output a list of data used in a Travis CI instance.
```

You can find detailed information about running an audit with the GitHub Actions Importer in the documentation that is available once you are granted access to the public preview.

#### Forecast

The `forecast` subcommand can be used to forecast GitHub Actions usage based on historical pipeline usage.

To run a forecast, use the following command to determine the options that are relevant to you:
You can find detailed information about using environment variables in the platform-specific documentation.

```bash
$ gh actions-importer forecast -h
Description:
Forecasts GitHub Actions usage from historical pipeline utilization.

[...]

Commands:
azure-devops Forecasts GitHub Actions usage from historical Azure DevOps pipeline utilization.
jenkins Forecasts GitHub Actions usage from historical Jenkins pipeline utilization.
gitlab Forecasts GitHub Actions usage from historical GitLab pipeline utilization.
circle-ci Forecasts GitHub Actions usage from historical CircleCI pipeline utilization.
travis-ci Forecasts GitHub Actions usage from historical Travis CI pipeline utilization.
github Forecasts GitHub Actions usage from historical GitHub pipeline utilization.
```
### Documentation

You can find detailed information about running a forecast with the GitHub Actions Importer in the documentation that is available once you are granted access to the public preview.
Detailed information about how to use GitHub Actions Importer can be found in the [documentation](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-github-actions-importer).

#### Dry run
### Recordings

The `dry-run` subcommand can be used to convert a pipeline to its GitHub Actions equivalent and write the workflow to your local filesystem.
You can access recorded demos of GitHub Actions Importer performing migrations to Actions from the following CI/CD platforms:
- [Azure DevOps](https://youtu.be/gG-2bkmBRlI)
- [CircleCI](https://youtu.be/YkFnNEyM9Hg)
- [GitLab](https://youtu.be/3t5ywu0_qk4)
- [Jenkins](https://youtu.be/WqiGP6h4fa0)
- [Travis CI](https://youtu.be/ndc-FNa_X3c)

To run a dry run, use the following command to determine the options that are relevant to you:
### Self-guided learning

```bash
$ gh actions-importer dry-run -h
Description:
Convert a pipeline to a GitHub Actions workflow and output its yaml file.

[...]

Commands:
azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and output its yaml file.
circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and output the yaml file(s).
gitlab Convert a GitLab pipeline to a GitHub Actions workflow and output the yaml file.
jenkins Convert a Jenkins job to a GitHub Actions workflow and output its yaml file.
travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and output its yaml file.
```
The GitHub Actions Importer labs repository contains platform-specific learning paths that teach you how to use GitHub Actions Importer and how to approach migrations to GitHub Actions. To learn more, see the [GitHub Actions Importer labs repository](https://github.com/actions/importer-labs/tree/main#readme).

You can find detailed information about running a dry run with the GitHub Actions Importer in the documentation that is available once you are granted access to the public preview.
## Product roadmap

#### Migrate
To learn about new features coming to GitHub Actions Importer, see the [GitHub Public Roadmap](https://github.com/orgs/github/projects/4247).

The `migrate` subcommand can be used to convert a pipeline to its GitHub Actions equivalent and then create a pull request with the contents.
## How to offer feedback or make a feature request

To run a migration, use the following command to determine the options that are relevant to your use case:

```bash
$ gh actions-importer migrate -h
Description:
Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.

[...]

Commands:
azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and open a pull request with the changes.
circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and open a pull request with the changes.
gitlab Convert a GitLab pipeline to a GitHub Actions workflow and open a pull request with the changes.
jenkins Convert a Jenkins job to a GitHub Actions workflow and open a pull request with the changes.
travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and and open a pull request with the changes.
```
If you would like to offer feedback or make a feature request, please create a new discussion [here](https://github.com/github/gh-actions-importer/discussions/new/choose).

You can find detailed information about running a migration with the GitHub Actions Importer in the documentation that is available once you are granted access to the public preview.
## How to request support
If you need further assistance, you can file a support ticket [here](https://support.github.com).
56 changes: 56 additions & 0 deletions docs/azure_devops/Ant.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Ant task

## Azure DevOps input

```yaml
- task: Ant@1
inputs:
buildFile: 'build.xml' # Required, alias: antBuildFile
options: -DmyProperty=myPropertyValue # Optional
targets: build-test # Optional
publishJUnitResults: true # Required
testResultsFiles: '**/TEST-*.xml' # Required when publishJUnitResults == True
testRunTitle: "Test Run Title" # Optional
antHomeDirectory: ANT_HOME # Optional, alias: antHomeUserInputPath
javaHomeOption: 'JDKVersion' # Options: jDKVersion, path, Alias: javaHomeSelection
jdkVersionOption: 'default' # Optional. Options: default, 1.11, 1.10, 1.9, 1.8, 1.7, 1.6, Alias: jdkVersion
jdkUserInputDirectory: # Required when javaHomeOption == Path, Alias: jdkUserInputPath
jdkArchitectureOption: 'x64' # Optional. Options: x86, x64, Alias: jdkArchitecture
```
### Transformed Github Action
```yaml
- name: Set up JDK 1.11
uses: actions/[email protected]
with:
java-version: '1.11'
- run: ant -DmyProperty=myPropertyValue -buildfile build.xml build-test
env:
ANT_HOME: ANT_HOME_DIR
- name: Publish test results
uses: EnricoMi/[email protected]
if: always()
with:
comment_title: Test Run Title
files: "**/TEST-*.xml"
```
```yaml
# publishJUnitResults: false
- name: Set up JDK 1.11
uses: actions/[email protected]
with:
java-version: '1.11'
- run: ant -DmyProperty=myPropertyValue -buildfile build.xml build-test
env:
ANT_HOME: ANT_HOME_DIR
```
### Unsupported inputs
- codeCoverageToolOptions, alias: codeCoverageTool
- codeCoverageClassFilesDirectories, alias: classFilesDirectories
- codeCoverageClassFilter, alias: classFilter
- codeCoverageSourceDirectories, alias: srcDirectories
- codeCoverageFailIfEmpty, alias: failIfCoverageEmpty
50 changes: 50 additions & 0 deletions docs/azure_devops/ArchiveFiles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# ArchiveFiles task

## Azure DevOps input

```yaml
steps:
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.BinariesDirectory)' # Required, Default: $(Build.BinariesDirectory)
includeRootFolder: true # Required
archiveType: 'zip' # Required, Options: zip, 7z, tar, wim
tarCompression: 'gz' # Optional, Options: gz, bz2, xz, None. Default: 'gz'
sevenZipCompression: "9" # Default: 5
archiveFile: 'archive_file' # Required, Default: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip
replaceExistingArchive: true # Required
verbose: false # Optional
quiet: false # Optional
```
### Transformed Github Action
Note:
- incoming input for archive_file needs to specify extension type. It is not added in transformation.
- Zip uses 7z compression
```yaml

- name: Tar files
run: tar -cf archive_file $(Build.BinariesDirectory) --overwrite
```
```yaml

- name: Zip files
run: 7z u archive_file $(Build.BinariesDirectory)
```
```yaml

- name: 7z files
run: 7z u -mx=9 archive_file $(Build.BinariesDirectory)
```
### Unsupported inputs
- archiveType (wim)
- quiet
- verbose (7z, zip)
- sevenzipcompression (zip)
60 changes: 60 additions & 0 deletions docs/azure_devops/AzureAppServiceManage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Azure App Service Manage task

## Azure DevOps input

```yaml
# Azure App Service manage
# Start, stop, restart, slot swap, slot delete, install site extensions or enable continuous monitoring for an Azure App Service
- task: AzureAppServiceManage@0
inputs:
azureSubscription: # Required, Alias: ConnectedServiceName
action: 'Swap Slots' # Optional. Default: Swap Slots
# Options: Swap Slots, Start Swap With Preview, Complete Swap, Cancel Swap, Start Azure App Service, Stop Azure App Service, Restart Azure App Service, Delete Slot, Install Extensions, Enable Continuous Monitoring, Start all continuous webjobs, Stop all continuous webjobs
webAppName: "App Name" # Required
specifySlotOrASE: false # Optional, Alias: SpecifySlot
resourceGroupName: # Required when action == Swap Slots || Action == Delete Slot || SpecifySlot == True
sourceSlot: # Required when action == Swap Slots
swapWithProduction: true # Optional, Default: true
targetSlot: # Required when action == Swap Slots && SwapWithProduction == False
preserveVnet: false # Optional, Default: false
slot: 'production' # Required when action == Delete Slot || SpecifySlot == True, Default: production
# Unsupported
extensionsList: # Required when action == Install Extensions
outputVariable: # Optional
appInsightsResourceGroupName: # Required when action == Enable Continuous Monitoring
applicationInsightsResourceName: # Required when action == Enable Continuous Monitoring
applicationInsightsWebTestName: # Optional
```
### Transformed Github Action
```yaml
- uses: Azure/login@v1
with:
creds: "${{ secrets.AZURE_CREDENTIALS }}"
- uses: azure/[email protected]
with:
# Action - Start & Stop
inlineScript: az webapp start --name "web-app" --resource-group "app-resource-group" --subscription "Azure Subscription"
# Action - Delete Slot
inlineScript: az webapp deployment slot delete --name "web-app" --resource-group "app-resource-group" --subscription "Azure Subscription" --slot "staging"
# Action - Swap Slots, add action field for Start With Preview, Complete Swap, Cancel Swap
inlineScript: az webapp deployment slot swap --name "web-app" --resource-group "app-resource-group" --subscription "Azure Subscription" --slot "staging" --target-slot "targetSlot" --preserve-vnet false --action {preview, swap, reset}
# Start/Stop all continuous WebJobs
inlineScript: |-
WEB_JOBS="$(az webapp webjob continuous list --name "service-app" --resource-group "service-resource-group" --subscription "Azure Subscription" --query "[].name" --output tsv)"
echo "$WEB_JOBS" | while read line ; do
web_job_name="${line##*/}"
az webapp webjob continuous start --name "service-app" --resource-group "service-resource-group" --subscription "Azure Subscription" --slot "slot-staging" --webjob-name "$web_job_name"
done
```
### Unsupported inputs
- Enable Continuous Monitoring(Action)
- Install Extensions(Action)
- ExtensionsList(Install Extensions)
- OutputVariable(Install Extensions)
- AppInsightsResourceGroupName(Enable Continuous Monitoring)
- ApplicationInsightsResourceName(Enable Continuous Monitoring)
- ApplicationInsightsWebTestName(Enable Continuous Monitoring)
Loading

0 comments on commit 0fb03fa

Please sign in to comment.